tessl/npm-gatsby-plugin-sharp

Wrapper of the Sharp image manipulation library for Gatsby plugins

1.07x

Quality

Pending

Does it follow best practices?

Impact

57%

1.07x

Average score across 10 eval scenarios

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Image Processing

Name: tessl/npm-gatsby-plugin-sharp
Rating: 57.99999999999999 (1 reviews)
Author: tessl

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

Capabilities

Queue Image Resizing

Queues a single image transformation job with specified parameters. This is the primary function for processing individual images.

/**
 * Queues a single image transformation job
 * @param options - Configuration object
 * @param options.file - Gatsby file node to process
 * @param options.args - Transform arguments specifying output parameters
 * @param options.reporter - Gatsby reporter instance for logging
 * @returns Promise resolving to processed image result
 */
function queueImageResizing(options: {
  file: FileNode;
  args: ITransformArgs;
  reporter: Reporter;
}): Promise<ImageResult>;

interface ImageResult {
  src: string;           // URL path to processed image
  absolutePath: string;  // Absolute file system path
  width: number;         // Output image width in pixels
  height: number;        // Output image height in pixels
  aspectRatio: number;   // Width/height ratio
  originalName: string;  // Original filename
  finishedPromise: Promise<void>; // Promise that resolves when processing completes
}

Usage Examples:

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

// Basic image resize
const result = await sharp.queueImageResizing({
  file: fileNode,
  args: {
    width: 800,
    height: 600,
    quality: 80
  },
  reporter
});

// WebP conversion with crop
const webpResult = await sharp.queueImageResizing({
  file: fileNode,
  args: {
    width: 1200,
    toFormat: "webp",
    quality: 85,
    fit: "cover",
    cropFocus: "attention"
  },
  reporter
});

// Grayscale transformation
const bwResult = await sharp.queueImageResizing({
  file: fileNode,
  args: {
    width: 500,
    grayscale: true,
    quality: 75
  },
  reporter
});

Batch Queue Image Resizing

Processes multiple transformations of the same source image efficiently in a single batch operation.

/**
 * Queues multiple image transformations for a single image in batch
 * @param options - Configuration object
 * @param options.file - Gatsby file node to process
 * @param options.transforms - Array of transform argument objects
 * @param options.reporter - Gatsby reporter instance for logging
 * @returns Promise resolving to array of processed image results
 */
function batchQueueImageResizing(options: {
  file: FileNode;
  transforms: ITransformArgs[];
  reporter: Reporter;
}): Promise<ImageResult[]>;

Usage Examples:

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

// Generate multiple sizes of the same image
const sizes = await sharp.batchQueueImageResizing({
  file: fileNode,
  transforms: [
    { width: 400, quality: 80 },
    { width: 800, quality: 80 },
    { width: 1200, quality: 80 },
    { width: 1600, quality: 80 }
  ],
  reporter
});

// Generate multiple formats
const formats = await sharp.batchQueueImageResizing({
  file: fileNode,
  transforms: [
    { width: 800, toFormat: "jpg", quality: 85 },
    { width: 800, toFormat: "webp", quality: 80 },
    { width: 800, toFormat: "avif", quality: 75 }
  ],
  reporter
});

Resize Function (Alias)

Alias for queueImageResizing for backward compatibility.

/**
 * Alias for queueImageResizing function
 */
const resize = queueImageResizing;

Transform Arguments

Core Transform Parameters

interface ITransformArgs {
  /** Output width in pixels */
  width?: number;
  /** Output height in pixels */
  height?: number;
  /** Image quality (1-100) */
  quality?: number;
  /** Output format: "jpg", "png", "webp", "avif", "tiff" */
  toFormat?: string;
  /** Crop focus for resizing: "center", "top", "bottom", "left", "right", "attention", etc. */
  cropFocus?: number | string;
  /** Background color for transparent areas */
  background?: string;
  /** How to resize: "cover", "contain", "fill", "inside", "outside" */
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  /** Convert to grayscale */
  grayscale?: boolean;
  /** Rotation angle in degrees */
  rotate?: number;
  /** Trim whitespace pixels */
  trim?: number;
  /** Duotone effect configuration */
  duotone?: {
    highlight: string;  // Hex color for highlights
    shadow: string;     // Hex color for shadows
    opacity?: number;   // Effect opacity (0-1)
  };
  /** PNG compression level (0-9) */
  pngCompressionLevel?: number;
  /** JPEG quality (overrides general quality) */
  jpegQuality?: number;
  /** PNG quality (overrides general quality) */
  pngQuality?: number;
  /** WebP quality (overrides general quality) */
  webpQuality?: number;
  /** Use progressive JPEG encoding */
  jpegProgressive?: boolean;
  /** Maximum width for fluid images */
  maxWidth?: number;
  /** Maximum height for fluid images */
  maxHeight?: number;
  /** Base64 thumbnail width */
  base64Width?: number;
  /** Path prefix for URLs */
  pathPrefix?: string;
}

Fit Options

The fit parameter controls how images are resized:

cover (default): Crop to cover the entire area, maintaining aspect ratio
contain: Scale to fit within dimensions, maintaining aspect ratio
fill: Stretch to exact dimensions, ignoring aspect ratio
inside: Scale to fit inside dimensions, maintaining aspect ratio
outside: Scale to cover dimensions, maintaining aspect ratio

Crop Focus Options

The cropFocus parameter controls which part of the image to focus on when cropping:

center: Focus on center of image
top, bottom, left, right: Focus on specific edge
attention: Automatic focus on most interesting area
entropy: Focus on area with highest entropy (most detail)
Custom gravity values: Sharp gravity constants for precise control

Processing Pipeline

Images are processed through the following pipeline:

Input Validation: Check file exists and is a valid image format
Metadata Extraction: Read dimensions, format, and other metadata
Transform Application: Apply resize, crop, format conversion, and effects
Output Generation: Write processed image to filesystem
Result Creation: Generate result object with paths and metadata

Performance Considerations

Batch Processing: Use batchQueueImageResizing for multiple transforms of the same source image
Quality Settings: Balance file size and visual quality with appropriate quality values
Format Selection: Choose optimal formats (WebP/AVIF for modern browsers, JPEG/PNG for fallbacks)
Concurrency: Plugin automatically manages concurrency based on CPU cores
Caching: Results are cached based on content digest and transform parameters

tessl/npm-gatsby-plugin-sharp