Plugin Configuration

/**
 * Sets global plugin options
 * @param opts - Configuration options object
 * @returns Updated plugin options
 */
function setPluginOptions(opts: Record<string, string>): ISharpPluginOptions;

/**
 * Retrieves current plugin options
 * @returns Current plugin options
 */
function getPluginOptions(): ISharpPluginOptions;

/**
 * Gets default plugin options
 * @returns Default plugin options
 */
function getPluginOptionsDefaults(): ISharpPluginOptions;

interface ISharpPluginOptions {
  /** Width of generated base64 preview images */
  base64Width?: number;
  /** Force specific format for base64 images */
  forceBase64Format?: "png" | "webp" | "jpg" | string;
  /** Use mozJpeg encoder for JPEG processing */
  useMozJpeg?: boolean;
  /** Strip metadata from processed images */
  stripMetadata?: boolean;
  /** Enable lazy image generation in development */
  lazyImageGeneration?: boolean;
  /** Default quality for image processing (1-100) */
  defaultQuality: number;
  /** Level of sensitivity to invalid images */
  failOn?: "none" | "truncated" | "error" | "warning";
  /** Default settings for gatsby-plugin-image */
  defaults?: PluginOptionsDefaults;
}

import { setPluginOptions, getPluginOptions } from "gatsby-plugin-sharp";

// Set plugin options
const options = setPluginOptions({
  defaultQuality: "85",
  base64Width: "30",
  stripMetadata: "false",
  useMozJpeg: "true"
});

// Get current options
const currentOptions = getPluginOptions();
console.log(`Default quality: ${currentOptions.defaultQuality}`);

// Get default options
const defaults = getPluginOptionsDefaults();
console.log(`Default base64 width: ${defaults.base64Width}`);

/**
 * Creates standardized transform options object
 * @param args - Transform arguments
 * @returns Processed transform options with defaults applied
 */
function createTransformObject(args: ITransformArgs): Partial<ITransformArgs>;

interface ITransformArgs {
  /** Output width in pixels */
  width?: number;
  /** Output height in pixels */
  height?: number;
  /** Crop focus area for resizing */
  cropFocus?: number | string;
  /** Output format */
  toFormat?: string;
  /** PNG compression level (0-9) */
  pngCompressionLevel?: number;
  /** Image quality (1-100) */
  quality?: 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;
  /** Convert to grayscale */
  grayscale?: boolean;
  /** Rotation angle in degrees */
  rotate?: number;
  /** Trim whitespace pixels */
  trim?: number;
  /** Duotone effect configuration */
  duotone?: {
    highlight: string;
    shadow: string;
    opacity?: number;
  };
  /** Resize fit mode */
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  /** Background color for transparent areas */
  background?: string;
  /** Path prefix for generated URLs */
  pathPrefix?: string;
  /** Maximum width for fluid images */
  maxWidth?: number;
  /** Maximum height for fluid images */
  maxHeight?: number;
  /** Base64 thumbnail width */
  base64Width?: number;
}

import { createTransformObject } from "gatsby-plugin-sharp";

// Create transform object with defaults
const transform = createTransformObject({
  width: 800,
  height: 600,
  quality: 85,
  toFormat: "webp",
  fit: "cover"
});

// Transform object filters out undefined values and applies defaults
console.log(transform);
// { width: 800, height: 600, quality: 85, toFormat: "webp", fit: "cover", jpegProgressive: true, pngCompressionLevel: 9 }

/**
 * Merges user arguments with plugin defaults for gatsby-plugin-image
 * @param args - User-provided image arguments
 * @returns Merged configuration with defaults applied
 */
function mergeDefaults(args: ISharpGatsbyImageArgs): PluginOptionsDefaults & ISharpGatsbyImageArgs;

/**
 * Normalizes and validates transform options
 * @param pluginOptions - Plugin configuration
 * @param args - Transform arguments
 * @param fileExtension - File extension for format inference
 * @param defaultArgs - Additional default arguments
 * @returns Processed options with validation and defaults applied
 */
function healOptions(
  pluginOptions: Pick<ISharpPluginOptions, "defaultQuality" | "base64Width">,
  args: ITransformArgs,
  fileExtension?: string,
  defaultArgs?: Record<string, any>
): Partial<IGeneralArgs> & { quality: number } & ITransformArgs;

/**
 * Strips default values for minimal transform arguments
 * @param args - Transform arguments
 * @param pluginOptions - Plugin options for comparison
 * @returns Minimal transform arguments with defaults removed
 */
function removeDefaultValues(
  args: ITransformArgs,
  pluginOptions: ISharpPluginOptions
): Partial<ITransformArgs>;

import { mergeDefaults, healOptions, removeDefaultValues } from "gatsby-plugin-sharp";

// Merge with defaults for gatsby-plugin-image
const mergedArgs = mergeDefaults({
  layout: "constrained",
  width: 800,
  placeholder: "blurred"
});

// Heal and validate options
const processedOptions = healOptions(
  { defaultQuality: 80, base64Width: 20 },
  { width: 800, quality: 85 },
  "jpg"
);

// Remove default values for minimal payload
const minimalArgs = removeDefaultValues(
  { width: 800, quality: 50, jpegProgressive: true },
  getPluginOptions()
);

const pluginDefaults = {
  base64Width: 20,                    // Base64 thumbnail width
  forceBase64Format: "",              // No forced format
  useMozJpeg: process.env.GATSBY_JPEG_ENCODER === "MOZJPEG",
  stripMetadata: true,                // Strip EXIF data
  lazyImageGeneration: true,          // Enable lazy loading in development
  defaultQuality: 50,                 // Default image quality
  failOn: "warning"                   // Fail on warnings
};

const generalArgs = {
  quality: 50,                        // Default quality
  jpegQuality: undefined,             // Use general quality
  pngQuality: undefined,              // Use general quality
  webpQuality: undefined,             // Use general quality
  jpegProgressive: true,              // Progressive JPEG
  pngCompressionLevel: 9,             // Maximum PNG compression
  pngCompressionSpeed: 4,             // PNG compression speed
  base64: true,                       // Generate base64 placeholders
  grayscale: false,                   // No grayscale conversion
  duotone: undefined,                 // No duotone effect
  pathPrefix: "",                     // No path prefix
  toFormat: "",                       // Auto-detect format
  toFormatBase64: "",                 // Auto-detect base64 format
  rotate: 0                           // No rotation
};

const DEFAULT_PIXEL_DENSITIES = [0.25, 0.5, 1, 2]; // Standard pixel densities
const DEFAULT_FLUID_SIZE = 800;                      // Default fluid image size
const DEFAULT_BREAKPOINTS = [750, 1080, 1366, 1920]; // Standard responsive breakpoints
const DOMINANT_COLOR_IMAGE_SIZE = 200;               // Size for dominant color calculation
const DEFAULT_BLURRED_IMAGE_WIDTH = 20;              // Blurred placeholder width

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-sharp",
      options: {
        defaultQuality: 75,
        base64Width: 30,
        stripMetadata: false,
        useMozJpeg: true,
        failOn: "error",
        defaults: {
          formats: ["auto", "webp"],
          placeholder: "blurred",
          quality: 80,
          breakpoints: [640, 768, 1024, 1280, 1920],
          backgroundColor: "transparent"
        }
      }
    }
  ]
};

// gatsby-config.js with comprehensive options
module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-sharp",
      options: {
        defaultQuality: 85,
        base64Width: 40,
        forceBase64Format: "webp",
        stripMetadata: true,
        useMozJpeg: process.env.NODE_ENV === "production",
        failOn: "warning",
        defaults: {
          formats: ["auto", "webp", "avif"],
          placeholder: "dominantColor",
          quality: 90,
          breakpoints: [480, 768, 1024, 1200, 1600],
          backgroundColor: "#f8f9fa",
          transformOptions: {
            fit: "cover",
            cropFocus: "attention"
          },
          jpgOptions: {
            quality: 95,
            progressive: true
          },
          pngOptions: {
            quality: 90,
            compressionLevel: 6
          },
          webpOptions: {
            quality: 85
          },
          avifOptions: {
            quality: 80
          },
          blurredOptions: {
            width: 40,
            toFormat: "webp"
          }
        }
      }
    }
  ]
};

import { setPluginOptions } from "gatsby-plugin-sharp";

// Override options at runtime
setPluginOptions({
  defaultQuality: "90",
  base64Width: "25",
  stripMetadata: "false"
});

// Create custom transform with overrides
const customTransform = createTransformObject({
  width: 1200,
  quality: 95,
  toFormat: "avif",
  fit: "cover",
  cropFocus: "entropy"
});

# Use mozJpeg encoder for JPEG processing
GATSBY_JPEG_ENCODER=MOZJPEG

# Enable lazy image generation in CI
GATSBY_ENABLE_LAZY_IMAGES_IN_CI=true

# Disable external job processing
ENABLE_GATSBY_EXTERNAL_JOBS=false

// Automatic validation of dimension values
const validateDimensions = (options: ITransformArgs) => {
  ["width", "height", "maxWidth", "maxHeight"].forEach(prop => {
    if (typeof options[prop] !== "undefined" && options[prop] < 1) {
      throw new Error(
        `${prop} has to be a positive int larger than zero (> 0), now it's ${options[prop]}`
      );
    }
  });
};

// Automatic format normalization
const normalizeFormat = (format: string) => {
  if (format === "jpeg") return "jpg";
  return format.toLowerCase();
};

// Quality value parsing and validation
const normalizeQuality = (quality: any) => {
  const parsed = parseInt(quality, 10);
  return Math.max(1, Math.min(100, parsed));
};