or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

gatsby-integration.mdimage-analysis-utilities.mdimage-data-generation.mdimage-processing.mdindex.mdlegacy-responsive-images.mdplugin-configuration.md
tile.json

tessl/npm-gatsby-plugin-sharp

Wrapper of the Sharp image manipulation library for Gatsby plugins

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-plugin-sharp@5.15.x

To install, run

npx @tessl/cli install tessl/npm-gatsby-plugin-sharp@5.15.0

index.mddocs/

Gatsby Plugin Sharp

Gatsby Plugin Sharp is a wrapper around the Sharp image manipulation library specifically designed for Gatsby plugins and applications. It provides optimized image processing capabilities with excellent out-of-the-box settings for common web image formats and serves as a foundation for other Gatsby image processing plugins.

Package Information

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

Core Imports

// Core image processing functions
const {
  queueImageResizing,
  batchQueueImageResizing,
  generateImageData,
  base64,
  fluid,
  fixed,
  stats,
  getImageSizeAsync,
  getDominantColor,
  // Legacy aliases
  resize,           // alias for queueImageResizing
  sizes,            // alias for fluid
  resolutions,      // alias for fixed
  // Deprecated functions
  traceSVG,         // deprecated, falls back to base64
  getImageSize,     // deprecated sync version, use getImageSizeAsync
  generateBase64,   // internal but exported
  // Configuration
  setActions
} = require("gatsby-plugin-sharp");

For TypeScript:

import {
  queueImageResizing,
  batchQueueImageResizing,
  generateImageData,
  base64,
  fluid,
  fixed,
  stats,
  getImageSizeAsync,
  getDominantColor,
  // Legacy aliases
  resize,           // alias for queueImageResizing
  sizes,            // alias for fluid
  resolutions,      // alias for fixed
  // Deprecated functions
  traceSVG,         // deprecated, falls back to base64
  getImageSize,     // deprecated sync version
  generateBase64,   // internal but exported
  // Configuration
  setActions,
  // Types
  type ISharpPluginOptions,
  type ITransformArgs,
  type FileNode,
  type IImageMetadata,
  type IImageDataArgs
} from "gatsby-plugin-sharp";

Basic Usage

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

// Process a single image with transformations
const result = await sharp.queueImageResizing({
  file: fileNode, // Gatsby file node
  args: {
    width: 800,
    height: 600,
    quality: 75,
    toFormat: "webp"
  },
  reporter
});

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

// Get image metadata
const metadata = await sharp.getImageSizeAsync(fileNode);
console.log(metadata.width, metadata.height);

Architecture

Gatsby Plugin Sharp is built around several key components:

  • Core Processing Functions: Main image transformation functions (queueImageResizing, batchQueueImageResizing) that handle individual and batch image processing
  • Legacy Responsive API: Fluid and fixed image functions for backward compatibility with older Gatsby image workflows
  • Modern Image API: generateImageData function compatible with gatsby-plugin-image for modern responsive images
  • Utility Functions: Helper functions for image analysis, color extraction, and dimension calculations
  • Plugin Integration: Gatsby lifecycle hooks for seamless integration with Gatsby's build process and development server
  • Worker Queue System: Asynchronous job processing system for handling image transformations efficiently

Capabilities

Image Processing

Core image transformation and processing functionality for generating optimized web images with various formats, sizes, and quality settings.

function queueImageResizing(options: {
  file: FileNode;
  args: ITransformArgs;
  reporter: Reporter;
}): Promise<ImageResult>;

function batchQueueImageResizing(options: {
  file: FileNode;
  transforms: ITransformArgs[];
  reporter: Reporter;
}): Promise<ImageResult[]>;

Image Processing

Modern Image Data Generation

Modern responsive image data generation compatible with gatsby-plugin-image, supporting multiple formats, breakpoints, and placeholder generation.

function generateImageData(options: {
  file: FileNode;
  args: ISharpGatsbyImageArgs;
  pathPrefix: string;
  reporter: Reporter;
  cache: GatsbyCache;
}): Promise<IGatsbyImageData | undefined>;

Image Data Generation

Legacy Responsive Images

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

function fluid(options: {
  file: FileNode;
  args: FluidArgs;
  reporter: Reporter;
  cache?: GatsbyCache;
}): Promise<FluidResult>;

function fixed(options: {
  file: FileNode;
  args: FixedArgs;
  reporter: Reporter;
  cache?: GatsbyCache;
}): Promise<FixedResult>;

Legacy Responsive Images

Image Analysis and Utilities

Utility functions for image analysis, metadata extraction, color analysis, and dimension calculations.

function getImageSizeAsync(file: FileNode): Promise<ImageDimensions>;
function getDominantColor(absolutePath: string): Promise<string>;
function stats(options: { file: FileNode; reporter: Reporter }): Promise<ImageStats>;

Image Analysis and Utilities

Plugin Configuration

Configuration management for plugin options, transform parameters, and default settings.

function setPluginOptions(opts: Record<string, string>): ISharpPluginOptions;
function getPluginOptions(): ISharpPluginOptions;
function createTransformObject(args: ITransformArgs): Partial<ITransformArgs>;

Plugin Configuration

Gatsby Integration

Gatsby plugin lifecycle hooks and development server integration for seamless image processing within Gatsby's build pipeline.

function onCreateDevServer(options: {
  app: Express.Application;
  cache: GatsbyCache;
  reporter: Reporter;
}): Promise<void>;

function onPreBootstrap(
  options: { actions: Actions; emitter: EventEmitter; cache: GatsbyCache },
  pluginOptions: ISharpPluginOptions
): Promise<void>;

Gatsby Integration

Legacy and Deprecated Functions

Function Aliases

The following function aliases are provided for backward compatibility:

// Legacy aliases - use primary functions instead
const resize = queueImageResizing;           // Alias for queueImageResizing
const sizes = fluid;                         // Alias for fluid
const resolutions = fixed;                   // Alias for fixed

Deprecated Functions

Warning: These functions are deprecated and may be removed in future versions.

/**
 * @deprecated TraceSVG generation is no longer supported, falls back to base64
 * Use base64() function instead
 */
function traceSVG(options: { file: FileNode; args: ITransformArgs; reporter: Reporter }): Promise<string>;

/**
 * @deprecated Synchronous version of getImageSizeAsync, will be removed in next major version
 * Use getImageSizeAsync() instead for better performance
 */
function getImageSize(file: FileNode): { width: number; height: number; type: string };

/**
 * Internal function exposed for compatibility - use base64() instead
 */
function generateBase64(options: { file: FileNode; args: ITransformArgs; reporter: Reporter }): Promise<ImageResult>;

Internal APIs

Warning: These APIs are internal and may change without notice. Use at your own risk.

/**
 * @internal Sets Gatsby actions for internal plugin use
 */
function setActions(actions: Actions): void;

/**
 * @internal Creates a processing job - unstable API
 */
function _unstable_createJob(job: JobV2, options: { reporter: Reporter }): Promise<void>;

/**
 * @internal Checks if lazy image generation is enabled
 */
function _lazyJobsEnabled(): boolean;

Core Types

interface FileNode {
  absolutePath: string;
  extension: string;
  internal: {
    contentDigest: string;
  };
  base: string;
  name: string;
  relativePath?: string;
}

interface ITransformArgs {
  width?: number;
  height?: number;
  quality?: number;
  jpegQuality?: number;
  pngQuality?: number;
  webpQuality?: number;
  toFormat?: string;
  cropFocus?: number | string;
  background?: string;
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  grayscale?: boolean;
  rotate?: number;
  trim?: number;
  pngCompressionLevel?: number;
  jpegProgressive?: boolean;
  duotone?: {
    highlight: string;
    shadow: string;
    opacity?: number;
  };
  pathPrefix?: string;
  maxHeight?: number;
  maxWidth?: number;
  base64Width?: number;
}

interface ImageResult {
  src: string;
  absolutePath: string;
  width: number;
  height: number;
  aspectRatio: number;
  originalName: string;
  finishedPromise: Promise<void>;
}

interface ISharpPluginOptions {
  base64Width?: number;
  forceBase64Format?: "png" | "webp" | "jpg" | string;
  useMozJpeg?: boolean;
  stripMetadata?: boolean;
  lazyImageGeneration?: boolean;
  defaultQuality: number;
  failOn?: "none" | "truncated" | "error" | "warning";
  defaults?: PluginOptionsDefaults;
}

interface IImageMetadata {
  width?: number;
  height?: number;
  format?: string;
  density?: number;
  dominantColor?: string;
}

interface IImageDataArgs {
  file: FileNode;
  args: ISharpGatsbyImageArgs;
  pathPrefix: string;
  cache: GatsbyCache;
  reporter: Reporter;
}