How to Adjust the Image Quality in next-export-optimize-images: Complete Configuration Guide

Set the quality property in your export-images.config.js file to a value between 1 and 100 (default is 75), and the CLI will automatically apply this compression level to all optimized images via Sharp.

The next-export-optimize-images library processes images during static export using Sharp's high-performance encoders. You control the compression quality through a centralized configuration option that serves as the default for all output formats, with optional per-format overrides for fine-tuned optimization.

Understanding the Quality Configuration API

The library exposes the quality setting through the Config type defined in src/utils/getConfig.ts. This optional field accepts a number from 1 to 100, defaulting to 75 when unspecified.

// src/utils/getConfig.ts (lines 53-56)
export type Config = {
  // ... other options
  quality?: number  // Default: 75
}

When the CLI initializes, it resolves the final quality value using nullish coalescing: config.quality ?? 75. This ensures that a default compression level is always available for the image processing pipeline.

Setting the Global Quality Value

Create or modify export-images.config.js in your project root to adjust the default compression for all supported formats (JPEG, PNG, WebP, and AVIF).

// export-images.config.js
module.exports = {
  quality: 85,  // Increase quality from default 75 to 85
  // ... other configuration options
};

Higher values produce visually clearer images with larger file sizes, while lower values reduce file size at the cost of image fidelity. The value 85 provides a common balance for web delivery.

Format-Specific Quality Overrides

For granular control, you can override the global quality setting for specific formats using the sharpOptions configuration object. When a format-specific quality is provided, it takes precedence over the global setting.

// export-images.config.js
module.exports = {
  quality: 80,  // Global default
  
  sharpOptions: {
    png: { 
      quality: 95,        // Higher quality for PNG screenshots
      compressionLevel: 9 // Maximum compression effort
    },
    jpg: { 
      quality: 70,        // Lower quality for JPEG photos
      progressive: true   // Enable progressive encoding
    },
    webp: {
      quality: 85         // Specific WebP optimization
    }
  }
};

How Quality Is Processed Internally

The quality value flows through several stages in the CLI pipeline defined in src/cli/index.ts:

1. Configuration Loading: The CLI imports getConfig() and resolves the quality constant:

// src/cli/index.ts (lines 54-55)
const config = getConfig()
const quality = config.quality ?? 75

2. Pipeline Injection: The resolved quality value is passed to getOptimizeResult(), where it interfaces with Sharp's encoder functions.

3. Sharp Integration: Inside getOptimizeResult (lines 96-124), the quality parameter is forwarded to Sharp's format-specific methods. Sharp's native encoders respect this value when generating the final compressed output for each image variant.

The library automatically handles the quality parameter for all supported formats, ensuring consistent compression behavior across your entire image set unless explicitly overridden via sharpOptions.

Running the Optimizer

After configuring your quality settings, execute the optimization process:

# Run via npx

npx next-export-optimize-images

# Or using the package binary directly

next-export-optimize-images

The CLI automatically loads export-images.config.js from your project root and applies the specified quality values during the image generation phase.

Summary

• Default quality is 75, defined in src/utils/getConfig.ts and applied when no configuration is provided.
• Global adjustment requires setting the quality property in export-images.config.js with a value between 1 and 100.
• Per-format control is available through sharpOptions, allowing specific quality values for PNG, JPEG, WebP, and AVIF formats.
• Implementation occurs in src/cli/index.ts, where the resolved quality value is injected into Sharp's encoding pipeline via getOptimizeResult.

Frequently Asked Questions

What is the default image quality in next-export-optimize-images?

The default quality is 75, as defined in the Config type within src/utils/getConfig.ts. This value provides a balanced trade-off between visual fidelity and file size for most web applications. If you do not specify a quality value in export-images.config.js, the CLI automatically falls back to 75 when calling Sharp's encoders.

Can I set different quality levels for different image formats?

Yes. While the global quality setting applies to all formats, you can override specific formats using the sharpOptions configuration object. For example, you might set sharpOptions.png.quality to 90 for lossless-looking screenshots while keeping JPEGs at 70 for photographs. These format-specific values take precedence over the global setting.

What quality value should I use for web images?

For most web applications, values between 70 and 85 provide optimal results. Use 70-75 for large photographic galleries where file size is critical, and 80-85 for hero images or graphics where visual clarity is more important. The default value of 75 works well as a general-purpose starting point, which you can adjust based on your specific performance budgets.

Does changing the quality setting affect build time?

No. The quality parameter only affects the compression algorithm's output fidelity, not the processing speed. Build times remain consistent regardless of whether you set quality to 1 or 100. However, higher quality settings produce larger file sizes, which may impact deployment times and end-user download speeds.

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