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

> Learn to apply custom sharpOptions for various image formats like PNG, JPG, WebP, and AVIF in next-export-optimize-images using format-specific settings in your config file.

- Repository: [d-suke/next-export-optimize-images](https://github.com/dc7290/next-export-optimize-images)
- Tags: how-to-guide
- Published: 2026-02-28

---

**The `next-export-optimize-images` plugin lets you define format-specific Sharp processing settings by declaring a `sharpOptions` object in [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) that demonstrates format-specific tuning. This example matches the test suite configuration found in [`__tests__/e2e/export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/__tests__/e2e/export-images.config.js) (lines 12-16), which sets WebP encoding to maximum speed.

```javascript
// 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`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) to compute options dynamically. This approach lets you switch between development and production optimization profiles without maintaining separate config files.

```javascript
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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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.