tessl/npm-gatsby-transformer-sharp

Gatsby transformer plugin for images using Sharp image processing library

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Modern Image Processing

Name: tessl/npm-gatsby-transformer-sharp
Author: tessl

The modern image processing API using gatsbyImageData field provides the recommended approach for handling images in Gatsby applications. This API integrates with gatsby-plugin-image to deliver optimized, responsive images with automatic format selection and lazy loading capabilities.

Capabilities

Gatsby Image Data

Creates optimized image data for use with gatsby-plugin-image components, providing automatic format optimization, responsive sizing, and performance enhancements.

/**
 * Generate optimized image data for gatsby-plugin-image
 * Available as a GraphQL field on ImageSharp nodes
 */
gatsbyImageData(
  /** The layout for the image (default: CONSTRAINED) */
  layout?: ImageLayout,
  /** Display width for FIXED layout, max width for CONSTRAINED layout */
  width?: Int,
  /** Display height for FIXED layout, max height for CONSTRAINED layout */
  height?: Int,
  /** Aspect ratio for cropping, overrides calculated ratio */
  aspectRatio?: Float,
  /** Placeholder type while image loads (default: DOMINANT_COLOR) */
  placeholder?: ImagePlaceholder,
  /** Image formats to generate (default: [AUTO, WEBP]) */
  formats?: ImageFormat[],
  /** Pixel densities to generate (default: [1, 2]) */
  outputPixelDensities?: Float[],
  /** Custom breakpoints for FULL_WIDTH layout */
  breakpoints?: Int[],
  /** Sizes attribute for responsive images */
  sizes?: String,
  /** Default quality for all formats */
  quality?: Int,
  /** JPG-specific options */
  jpgOptions?: JPGOptions,
  /** PNG-specific options */
  pngOptions?: PNGOptions,
  /** WebP-specific options */
  webpOptions?: WebPOptions,
  /** AVIF-specific options */
  avifOptions?: AVIFOptions,
  /** Image transformation options */
  transformOptions?: TransformOptions,
  /** Background color for letterboxing */
  backgroundColor?: String
): GatsbyImageData;

interface GatsbyImageData {
  layout: ImageLayout;
  width: number;
  height: number;
  images: {
    sources: ImageSource[];
    fallback: ImageFallback;
  };
  placeholder?: {
    fallback: string;
  };
  backgroundColor?: string;
}

interface ImageSource {
  srcSet: string;
  type: string;
  sizes?: string;
}

interface ImageFallback {
  src: string;
  srcSet: string;
  sizes?: string;
}

Usage Examples:

# Constrained responsive image (recommended)
query {
  file(relativePath: { eq: "hero.jpg" }) {
    childImageSharp {
      gatsbyImageData(
        layout: CONSTRAINED
        width: 800
        placeholder: BLURRED
        formats: [AUTO, WEBP, AVIF]
      )
    }
  }
}

# Fixed size image
query {
  file(relativePath: { eq: "avatar.jpg" }) {
    childImageSharp {
      gatsbyImageData(
        layout: FIXED
        width: 200
        height: 200
        placeholder: DOMINANT_COLOR
      )
    }
  }
}

# Full width hero image
query {
  file(relativePath: { eq: "banner.jpg" }) {
    childImageSharp {
      gatsbyImageData(
        layout: FULL_WIDTH
        height: 400
        formats: [AUTO, WEBP]
        breakpoints: [750, 1080, 1366, 1920]
      )
    }
  }
}

Format-Specific Options

Fine-grained control over image format generation and optimization settings.

interface JPGOptions {
  /** JPG quality (1-100) */
  quality?: Int;
  /** Enable progressive JPG (default: true) */
  progressive?: Boolean;
}

interface PNGOptions {
  /** PNG quality (1-100) */
  quality?: Int;
  /** PNG compression speed (1-10, default: 4) */
  compressionSpeed?: Int;
}

interface WebPOptions {  
  /** WebP quality (1-100) */
  quality?: Int;
}

interface AVIFOptions {
  /** AVIF quality (1-100) */
  quality?: Int;
  /** Enable lossless compression */
  lossless?: Boolean;
  /** Encoding speed (1-10) */
  speed?: Int;
}

Transform Options

Image transformation settings for cropping, rotation, and visual effects.

interface TransformOptions {
  /** Convert image to grayscale (default: false) */
  grayscale?: Boolean;
  /** Apply duotone color effect */
  duotone?: DuotoneGradient;
  /** Rotation angle in degrees (default: 0) */
  rotate?: Int;
  /** Trim transparent/similar-color pixels (default: false) */
  trim?: Float;
  /** Focus area for cropping (default: ATTENTION) */
  cropFocus?: ImageCropFocus;
  /** Resize behavior (default: COVER) */
  fit?: ImageFit;
}

interface DuotoneGradient {
  /** Highlight color (required) */
  highlight: String;
  /** Shadow color (required) */
  shadow: String;
  /** Effect opacity (0-100) */
  opacity?: Int;
}

Placeholder Options

Configuration for different placeholder types displayed during image loading.

interface BlurredOptions {
  /** Width of the blurred placeholder (default: 20px) */
  width?: Int;
  /** Format for the placeholder image */
  toFormat?: ImageFormat;
}

Usage Examples:

# Custom quality and format options
query {
  file(relativePath: { eq: "product.jpg" }) {
    childImageSharp {
      gatsbyImageData(
        width: 600
        quality: 90
        jpgOptions: { progressive: true }
        webpOptions: { quality: 85 }
        formats: [JPG, WEBP]
      )
    }
  }
}

# Grayscale with custom crop focus
query {
  file(relativePath: { eq: "portrait.jpg" }) {
    childImageSharp {
      gatsbyImageData(
        width: 300
        height: 400
        transformOptions: {
          grayscale: true
          cropFocus: NORTH
        }
      )
    }
  }
}

# Blurred placeholder with custom settings
query {
  file(relativePath: { eq: "background.jpg" }) {
    childImageSharp {
      gatsbyImageData(
        layout: FULL_WIDTH
        placeholder: BLURRED
        blurredOptions: {
          width: 40
          toFormat: JPG
        }
      )
    }
  }
}