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.
npm install gatsby-plugin-sharp// 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";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);Gatsby Plugin Sharp is built around several key components:
queueImageResizing, batchQueueImageResizing) that handle individual and batch image processinggenerateImageData function compatible with gatsby-plugin-image for modern responsive imagesCore 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[]>;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>;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>;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>;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>;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>;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 fixedWarning: 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>;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;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;
}