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

> Learn to adjust image quality in next-export-optimize-images. Configure the quality setting in export-images.config.js for optimal image compression using Sharp.

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

---

**Set the `quality` property in your [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts). This optional field accepts a number from 1 to 100, defaulting to 75 when unspecified.

```typescript
// 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`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) in your project root to adjust the default compression for all supported formats (JPEG, PNG, WebP, and AVIF).

```js
// 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.

```js
// 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`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/cli/index.ts):

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

```typescript
// 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:

```bash

# 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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts) and applied when no configuration is provided.
- **Global adjustment** requires setting the `quality` property in [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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.