or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

graphql-fragments.mdimage-resizing-utilities.mdindex.mdlegacy-image-processing.mdmodern-image-processing.md
tile.json

index.mddocs/

Gatsby Transformer Sharp

Gatsby Transformer Sharp is a Gatsby transformer plugin that creates ImageSharp nodes from image files supported by the Sharp image processing library. It provides GraphQL fields for processing images in various ways including resizing, cropping, and creating responsive images. This plugin works as part of Gatsby's unified GraphQL data layer, transforming static image files into optimized, responsive images for modern web applications.

Package Information

  • Package Name: gatsby-transformer-sharp
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install gatsby-transformer-sharp gatsby-plugin-sharp

Core Imports

This plugin works as part of Gatsby's plugin system and doesn't export functions directly. Instead, it provides GraphQL schema extensions.

Configuration in gatsby-config.js:

module.exports = {
  plugins: [
    `gatsby-plugin-sharp`, // Required peer dependency
    `gatsby-transformer-sharp`,
    // or with options:
    {
      resolve: `gatsby-transformer-sharp`,
      options: {
        checkSupportedExtensions: false,
      },
    },
  ],
}

GraphQL fragments for queries:

import { graphql } from "gatsby";
// Import fragments for different image types

Basic Usage

// gatsby-config.js - Plugin configuration
module.exports = {
  plugins: [
    `gatsby-source-filesystem`, // Source plugin for images
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
  ],
}

GraphQL query example:

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

Architecture

Gatsby Transformer Sharp operates within Gatsby's build-time data processing pipeline:

  • Node Creation: Transforms File nodes with supported image extensions into ImageSharp nodes
  • GraphQL Schema: Extends Gatsby's GraphQL schema with image processing fields and types
  • Processing Integration: Delegates actual image processing to gatsby-plugin-sharp
  • Fragment Library: Provides pre-built GraphQL fragments for common image query patterns
  • Error Handling: Includes comprehensive error reporting and troubleshooting guidance

Configuration

Plugin Options

interface GatsbyTransformerSharpOptions {
  /** Controls warning behavior for unsupported image formats (default: true) */
  checkSupportedExtensions?: boolean;
}

Supported image formats: .jpeg, .jpg, .png, .webp, .tif, .tiff, .avif

Capabilities

Modern Image Processing

The primary image processing API using gatsby-plugin-image for modern, performant images with automatic format optimization and responsive sizing.

// GraphQL field available on ImageSharp nodes
gatsbyImageData(
  layout: ImageLayout = CONSTRAINED,
  width: Int,
  height: Int,
  aspectRatio: Float,
  placeholder: ImagePlaceholder = DOMINANT_COLOR,
  formats: [ImageFormat] = [AUTO, WEBP],
  outputPixelDensities: [Float],
  breakpoints: [Int],
  sizes: String,
  quality: Int,
  jpgOptions: JPGOptions,
  pngOptions: PNGOptions,
  webpOptions: WebPOptions,
  avifOptions: AVIFOptions,
  transformOptions: TransformOptions,
  backgroundColor: String
): GatsbyImageData

Modern Image Processing

Legacy Image Processing

Deprecated fixed and fluid image processing APIs maintained for backward compatibility.

// GraphQL fields available on ImageSharp nodes (deprecated)
fixed(
  width: Int,
  height: Int,
  quality: Int,
  toFormat: ImageFormat,
  cropFocus: ImageCropFocus = ATTENTION,
  fit: ImageFit = COVER
): ImageSharpFixed

fluid(
  maxWidth: Int,
  maxHeight: Int,
  quality: Int,
  toFormat: ImageFormat,
  cropFocus: ImageCropFocus = ATTENTION,
  fit: ImageFit = COVER,
  sizes: String,
  srcSetBreakpoints: [Int]
): ImageSharpFluid

Legacy Image Processing

Image Resizing and Utilities

Simple image resizing and original image access for basic transformations and static image serving.

// GraphQL fields available on ImageSharp nodes
resize(
  width: Int,
  height: Int,
  quality: Int,
  toFormat: ImageFormat,
  cropFocus: ImageCropFocus = ATTENTION,
  fit: ImageFit = COVER
): ImageSharpResize

original(): ImageSharpOriginal

Image Resizing and Utilities

GraphQL Fragments

Pre-built GraphQL fragments for common image query patterns, optimizing query performance and developer experience.

// Available fragments for fixed images
GatsbyImageSharpFixed
GatsbyImageSharpFixed_withWebp
GatsbyImageSharpFixed_noBase64

// Available fragments for fluid images  
GatsbyImageSharpFluid
GatsbyImageSharpFluid_withWebp
GatsbyImageSharpFluid_noBase64

GraphQL Fragments

Core Types

enum ImageFormat {
  NO_CHANGE
  AUTO
  JPG
  PNG
  WEBP
  AVIF
}

enum ImageLayout {
  FIXED
  FULL_WIDTH
  CONSTRAINED
}

enum ImagePlaceholder {
  DOMINANT_COLOR
  TRACED_SVG  // Deprecated, falls back to DOMINANT_COLOR
  BLURRED
  NONE
}

enum ImageCropFocus {
  CENTER
  NORTH | NORTHEAST | EAST | SOUTHEAST
  SOUTH | SOUTHWEST | WEST | NORTHWEST
  ENTROPY
  ATTENTION
}

enum ImageFit {
  COVER
  CONTAIN
  FILL
  INSIDE
  OUTSIDE
}