How to Apply Custom SharpOptions for Different Image Formats in next-export-optimize-images

The next-export-optimize-images plugin lets you define format-specific Sharp processing settings by declaring a sharpOptions object in export-images.config.js with keys for png, jpg, webp, and avif.

When exporting a Next.js application as static HTML, next-export-optimize-images processes images through Sharp to generate optimized assets. You can apply custom sharpOptions for different image formats to control compression levels, encoding effort, and quality settings individually for PNG, JPEG, WebP, and AVIF outputs.

Configuring sharpOptions in export-images.config.js

The configuration loader at src/utils/getConfig.ts validates a sharpOptions field that accepts four optional keys: png, jpg, webp, and avif. Each key maps to a Sharp options object that the CLI later spreads into the corresponding Sharp method call.

According to the source code in src/utils/getConfig.ts (lines 71-78), the TypeScript definition expects objects compatible with Sharp’s method-specific options. When the build runs, the CLI in src/cli/index.ts (lines 95-126) merges these options with the global quality value and invokes the appropriate Sharp encoder.

Complete Configuration Example

Below is a production-ready export-images.config.js that demonstrates format-specific tuning. This example matches the test suite configuration found in __tests__/e2e/export-images.config.js (lines 12-16), which sets WebP encoding to maximum speed.

// export-images.config.js
module.exports = {
  quality: 80,                       // global quality fallback
  sharpOptions: {
    png: {
      compressionLevel: 9,           // max PNG compression
      palette: true,
    },
    jpg: {
      progressive: true,             // progressive JPEG
      mozjpeg: true,
    },
    webp: {
      effort: 0,                     // fastest WebP encoding
      lossless: false,
    },
    avif: {
      lossless: true,                // lossless AVIF output
      quality: 50,                   // overrides global quality for AVIF
    },
  },
  generateFormats: ['avif', 'webp'],
};

The sharpOptions object above is read by getConfig() and applied during the optimization pipeline. Each format object is passed directly to its respective Sharp method: sharp.png(), sharp.jpeg(), sharp.webp(), or sharp.avif().

How the CLI Applies sharpOptions During Build

During the export process, the CLI iterates over generated image variants and constructs Sharp instances with the merged options. As implemented in dc7290/next-export-optimize-images, the build script spreads the per-format options into the Sharp method calls, allowing individual control over encoding parameters.

The global quality setting acts as a default, but format-specific values in sharpOptions take precedence. For example, setting quality: 50 inside sharpOptions.avif overrides the global 80 for AVIF files only, while WebP and JPEG continue using the default.

Dynamic Configuration Based on Environment

While the library does not natively read environment variables for Sharp settings, you can export a function from export-images.config.js to compute options dynamically. This approach lets you switch between development and production optimization profiles without maintaining separate config files.

module.exports = () => ({
  quality: process.env.NODE_ENV === 'production' ? 85 : 60,
  sharpOptions: {
    webp: { 
      effort: process.env.WEBP_EFFORT === 'fast' ? 0 : 6 
    },
    jpg: { 
      progressive: process.env.NODE_ENV === 'production' 
    },
  },
});

Summary

• Define custom sharpOptions for different image formats by adding a sharpOptions object to export-images.config.js.
• Supported format keys are png, jpg, webp, and avif, matching Sharp’s method names.
• The CLI in src/cli/index.ts spreads these options into sharp.png(), sharp.jpeg(), sharp.webp(), and sharp.avif() calls during the build.
• Format-specific quality values override the global quality setting for that format only.
• Export a function from your config file to dynamically adjust options based on environment variables.

Frequently Asked Questions

Can I apply sharpOptions to a single image instead of globally?

No. The sharpOptions configuration applies to all images processed during the export. The plugin does not support per-image Sharp overrides through the config file. To process individual images differently, you must handle them outside the plugin’s pipeline using Sharp directly.

Does the global quality setting override format-specific quality?

No. When you specify a quality value inside a format-specific sharpOptions object (e.g., sharpOptions.avif.quality), that value takes precedence over the global quality setting. The global value serves as the fallback for formats without explicit quality definitions.

What happens if I omit a format key in sharpOptions?

If a format key is missing from sharpOptions, the plugin uses Sharp’s default settings for that format, merged with the global quality value. Omitting a key does not cause errors; it simply results in standard optimization without custom parameters.

Are sharpOptions available when using the plugin programmatically?

Yes. When importing the configuration utility directly from src/utils/getConfig.ts, the returned object includes the parsed sharpOptions. You can use these options to manually configure Sharp instances in custom scripts, though the CLI handles this automatically during normal builds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}