or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

gatsby-integration.md image-analysis-utilities.md image-data-generation.md image-processing.md index.md legacy-responsive-images.md plugin-configuration.md

tile.json

Legacy Responsive Images

Legacy fluid and fixed image APIs for backward compatibility with older Gatsby image workflows and plugins.

Capabilities

Fluid Images

Generates responsive image sets with multiple sizes and srcSet for fluid layouts that scale with container width.

/**
 * Generates responsive/fluid image set with multiple sizes and srcSet
 * @param options - Configuration object
 * @param options.file - Gatsby file node to process
 * @param options.args - Fluid image arguments
 * @param options.reporter - Gatsby reporter instance
 * @param options.cache - Optional Gatsby cache instance
 * @returns Promise resolving to fluid image object
 */
function fluid(options: {
  file: FileNode;
  args: FluidArgs;
  reporter: Reporter;
  cache?: GatsbyCache;
}): Promise<FluidResult>;

interface FluidResult {
  base64?: string;         // Base64 placeholder image
  aspectRatio: number;     // Width/height ratio
  src: string;            // Fallback image URL
  srcSet: string;         // Responsive image srcSet
  srcSetType: string;     // MIME type for srcSet
  sizes: string;          // CSS sizes attribute
  originalImg: string;    // URL to original/largest image
  originalName: string;   // Original filename
  density: number;        // Image density
  presentationWidth: number;  // Display width
  presentationHeight: number; // Display height
  tracedSVG?: string;     // Deprecated, falls back to base64
}

interface FluidArgs {
  maxWidth?: number;      // Maximum width for responsive sizes
  maxHeight?: number;     // Maximum height for responsive sizes
  quality?: number;       // Image quality (1-100)
  toFormat?: string;      // Output format
  cropFocus?: string | number; // Crop focus area
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  background?: string;    // Background color
  rotate?: number;        // Rotation angle
  grayscale?: boolean;    // Convert to grayscale
  duotone?: {            // Duotone effect
    highlight: string;
    shadow: string;
    opacity?: number;
  };
  base64?: boolean;      // Generate base64 placeholder
  base64Width?: number;  // Base64 thumbnail width
  srcSetBreakpoints?: number[]; // Custom breakpoints
  sizes?: string;        // Custom sizes attribute
  pathPrefix?: string;   // URL path prefix
}

Usage Examples:

const sharp = require("gatsby-plugin-sharp");

// Basic fluid image
const fluidResult = await sharp.fluid({
  file: fileNode,
  args: {
    maxWidth: 800,
    quality: 80
  },
  reporter
});

// Fluid image with custom breakpoints
const customFluid = await sharp.fluid({
  file: fileNode,
  args: {
    maxWidth: 1200,
    srcSetBreakpoints: [400, 600, 800, 1000, 1200],
    quality: 85,
    toFormat: "webp"
  },
  reporter,
  cache
});

// Fluid image with effects
const styledFluid = await sharp.fluid({
  file: fileNode,
  args: {
    maxWidth: 600,
    grayscale: true,
    duotone: {
      highlight: "#ff6b6b",
      shadow: "#4ecdc4"
    },
    base64: true,
    base64Width: 20
  },
  reporter
});

Fixed Images

Generates fixed-size images with density variants (1x, 1.5x, 2x) for high-DPI displays.

/**
 * Generates fixed-size image with density variants
 * @param options - Configuration object
 * @param options.file - Gatsby file node to process
 * @param options.args - Fixed image arguments
 * @param options.reporter - Gatsby reporter instance
 * @param options.cache - Optional Gatsby cache instance
 * @returns Promise resolving to fixed image object
 */
function fixed(options: {
  file: FileNode;
  args: FixedArgs;
  reporter: Reporter;
  cache?: GatsbyCache;
}): Promise<FixedResult>;

interface FixedResult {
  base64?: string;         // Base64 placeholder image
  aspectRatio: number;     // Width/height ratio
  width: number;          // Image width
  height: number;         // Image height
  src: string;            // Main image URL
  srcSet: string;         // High-DPI srcSet (1x, 1.5x, 2x)
  originalName: string;   // Original filename
  tracedSVG?: string;     // Deprecated, falls back to base64
}

interface FixedArgs {
  width?: number;         // Fixed width in pixels
  height?: number;        // Fixed height in pixels
  quality?: number;       // Image quality (1-100)
  toFormat?: string;      // Output format
  cropFocus?: string | number; // Crop focus area
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  background?: string;    // Background color
  rotate?: number;        // Rotation angle
  grayscale?: boolean;    // Convert to grayscale
  duotone?: {            // Duotone effect
    highlight: string;
    shadow: string;
    opacity?: number;
  };
  base64?: boolean;      // Generate base64 placeholder
  base64Width?: number;  // Base64 thumbnail width
  pathPrefix?: string;   // URL path prefix
}

Usage Examples:

const sharp = require("gatsby-plugin-sharp");

// Basic fixed image
const fixedResult = await sharp.fixed({
  file: fileNode,
  args: {
    width: 400,
    height: 300,
    quality: 80
  },
  reporter
});

// Fixed image with high quality and format conversion
const hqFixed = await sharp.fixed({
  file: fileNode,
  args: {
    width: 600,
    quality: 95,
    toFormat: "webp",
    fit: "cover",
    cropFocus: "attention"
  },
  reporter,
  cache
});

// Square fixed image with effects
const squareFixed = await sharp.fixed({
  file: fileNode,
  args: {
    width: 200,
    height: 200,
    fit: "cover",
    grayscale: true,
    base64: true
  },
  reporter
});

Legacy Aliases

Backward compatibility aliases for older API versions.

/**
 * Alias for fluid function
 */
const sizes = fluid;

/**
 * Alias for fixed function
 */
const resolutions = fixed;

Base64 Placeholder Generation

Generate Base64

Creates base64-encoded thumbnail images for use as placeholders while full images load.

/**
 * Generates base64-encoded thumbnail image
 * @param options - Configuration object
 * @param options.file - Gatsby file node
 * @param options.args - Transform arguments for placeholder
 * @param options.reporter - Gatsby reporter instance
 * @param options.cache - Optional Gatsby cache instance
 * @returns Promise resolving to base64 image data
 */
function base64(options: {
  file: FileNode;
  args: Base64Args;
  reporter: Reporter;
  cache?: GatsbyCache;
}): Promise<Base64Result>;

interface Base64Result {
  src: string;            // Base64 data URL
  width: number;          // Thumbnail width
  height: number;         // Thumbnail height
  aspectRatio: number;    // Width/height ratio
  originalName: string;   // Original filename
}

interface Base64Args {
  width?: number;         // Thumbnail width (default: 20)
  height?: number;        // Thumbnail height
  quality?: number;       // Thumbnail quality
  toFormat?: string;      // Thumbnail format
  toFormatBase64?: string; // Override format for base64
  cropFocus?: string | number; // Crop focus
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  background?: string;    // Background color
  grayscale?: boolean;    // Convert to grayscale
  rotate?: number;        // Rotation angle
  duotone?: {            // Duotone effect
    highlight: string;
    shadow: string;
    opacity?: number;
  };
}

Usage Examples:

const sharp = require("gatsby-plugin-sharp");

// Basic base64 placeholder
const placeholder = await sharp.base64({
  file: fileNode,
  args: { width: 20 },
  reporter
});

// High-quality base64 placeholder
const hqPlaceholder = await sharp.base64({
  file: fileNode,
  args: {
    width: 40,
    quality: 70,
    toFormatBase64: "webp"
  },
  reporter,
  cache
});

// Styled base64 placeholder
const styledPlaceholder = await sharp.base64({
  file: fileNode,
  args: {
    width: 30,
    grayscale: true,
    fit: "cover"
  },
  reporter
});

Lower-Level Base64 Generation

Direct base64 generation function for advanced use cases.

/**
 * Internal base64 generation function (lower-level)
 * @param options - Configuration object
 * @returns Promise resolving to base64 image data
 */
function generateBase64(options: {
  file: FileNode;
  args: Base64Args;
  reporter: Reporter;
}): Promise<Base64Result>;

Traced SVG (Deprecated)

Legacy traced SVG functionality that now falls back to blurred placeholders.

/**
 * Generates traced SVG placeholder (deprecated, falls back to base64)
 * @param args - Arguments object (same as base64)
 * @returns Promise resolving to base64 image src string
 * @deprecated This functionality is deprecated and falls back to blurred placeholders
 */
function traceSVG(args: Base64Args): Promise<string>;

Note: The traceSVG function is deprecated and will show a warning message. It falls back to generating blurred base64 placeholders instead.

Migration Considerations

From Legacy to Modern API

When migrating from legacy APIs to generateImageData:

// Legacy fluid API
const legacyFluid = await sharp.fluid({
  file: fileNode,
  args: { maxWidth: 800, quality: 80 },
  reporter
});

// Modern equivalent
const modernImage = await sharp.generateImageData({
  file: fileNode,
  args: {
    layout: "constrained",
    width: 800,
    quality: 80,
    placeholder: "blurred"
  },
  pathPrefix: "/",
  reporter,
  cache
});

Responsive Breakpoints

Legacy API uses automatic breakpoint generation or custom srcSetBreakpoints, while modern API uses breakpoints array:

// Legacy custom breakpoints
const legacyCustom = await sharp.fluid({
  file: fileNode,
  args: {
    maxWidth: 1200,
    srcSetBreakpoints: [400, 800, 1200]
  },
  reporter
});

// Modern custom breakpoints
const modernCustom = await sharp.generateImageData({
  file: fileNode,
  args: {
    layout: "constrained",
    width: 1200,
    breakpoints: [400, 800, 1200]
  },
  pathPrefix: "/",
  reporter,
  cache
});

Version

Tile

Files