# How to Configure Format Conversion (convertFormat) in next-export-optimize-images: PNG to WebP Guide

> Learn how to configure PNG to WebP format conversion with next-export-optimize-images. Add convertFormat to your export-images.config.js for optimized image generation.

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

---

**To convert PNG images to WebP during static export, add a `convertFormat` array to your [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) file containing tuples like `['png', 'webp']`, which triggers the library to generate additional optimized files while keeping the originals intact.**

The `next-export-optimize-images` library extends Next.js static exports with advanced image optimization capabilities. When you need to automatically transform source images into modern formats like WebP without manually reprocessing assets, the **`convertFormat`** configuration option provides a declarative way to handle format conversion during the build phase.

## Understanding the convertFormat Configuration Option

The `convertFormat` option accepts an array of tuples where each tuple defines a source-to-target format mapping.

In [`src/utils/getConfig.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts), the TypeScript definition declares the field as:

```typescript
convertFormat?: [beforeConvert: AllowedFormat, afterConvert: AllowedFormat][];

```

This structure requires the first element to match the original file extension and the second to specify the desired output format. According to [`src/utils/formatValidate.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/formatValidate.ts), the library supports `jpeg`, `jpg`, `png`, `webp`, and `avif` as valid values for both positions. Invalid entries throw an "Unauthorized format specified …" error at build time.

## How ConvertFormat Works Under the Hood

The core conversion logic resides in [`src/utils/buildOutputInfo.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/buildOutputInfo.ts) (lines 50-60). During the export process, the library checks each processed image against the `convertFormat` configuration.

When a match occurs between the image's original extension and a tuple's first element, the system validates both formats using the `formatValidate` utility. If validation passes, the extension is swapped to the target format for output generation. This process creates a new file with the converted extension alongside the original asset, leaving the source file untouched in the output directory.

## Configuring PNG to WebP Conversion

Setting up format conversion requires modifying your [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) file in the project root.

### Basic Configuration Example

To convert all PNG files to WebP format during export:

```javascript
// export-images.config.js
/**
 * @type {import('next-export-optimize-images').Config}
 */
module.exports = {
  convertFormat: [
    ['png', 'webp'],
  ],
}

```

With this configuration, an image referenced as `/photo.png` generates two files in the output directory: `photo.png` (original) and `photo.webp` (converted).

### Multiple Format Conversions

You can define multiple conversion rules by adding additional tuples to the array:

```javascript
module.exports = {
  convertFormat: [
    ['png', 'webp'],
    ['jpg', 'avif'],
  ],
}

```

This setup simultaneously converts PNG sources to WebP and JPEG sources to AVIF during the static export process.

## Legacy Status and Modern Alternatives

While `convertFormat` remains functional, the documentation marks it as **legacy** functionality that predates the library's `Picture` component. For projects requiring multiple fallback formats (such as providing both WebP and AVIF versions), the modern approach uses **`generateFormats`** combined with the `<Picture>` component:

```javascript
// export-images.config.js
module.exports = {
  generateFormats: ['webp', 'avif'],
}

```

```tsx
import { Picture } from 'next-export-optimize-images'

export default function Hero() {
  return (
    <Picture src="/images/hero.png" width={1200} height={800} alt="Hero" />
  )
}

```

The `generateFormats` option automatically creates alternative formats for every image, offering more flexibility than the one-to-one mapping of `convertFormat`.

## Summary

- Add `convertFormat` to [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) as an array of `[source, target]` tuples to enable automatic format conversion during `next export`.
- Valid formats defined in [`src/utils/formatValidate.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/formatValidate.ts) include `jpeg`, `jpg`, `png`, `webp`, and `avif`.
- The conversion logic in [`src/utils/buildOutputInfo.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/buildOutputInfo.ts) generates new files with swapped extensions while preserving originals.
- Consider migrating to `generateFormats` and the `<Picture>` component for modern multi-format support instead of relying on the legacy `convertFormat` approach.

## Frequently Asked Questions

### What file formats does convertFormat support?

The `convertFormat` option supports `jpeg`, `jpg`, `png`, `webp`, and `avif` as both source and target formats, as validated by the `formatValidate` utility in [`src/utils/formatValidate.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/formatValidate.ts). Any format outside this list triggers an "Unauthorized format specified" error during the build process.

### Does convertFormat replace the original image files?

No, the original files remain intact in the output directory. The configuration in [`src/utils/buildOutputInfo.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/buildOutputInfo.ts) generates additional files with the new extension, meaning a `photo.png` source produces both `photo.png` and `photo.webp` in the final static export.

### Why is convertFormat considered legacy?

The `convertFormat` feature predates the library's `<Picture>` component and is limited to one-to-one format mappings. Modern implementations should use `generateFormats` to create multiple optimized variants automatically, providing better browser compatibility through native responsive image techniques.

### Can I chain multiple conversions for the same source format?

While you can define multiple tuples in the `convertFormat` array, each source format should map to a single target to avoid conflicts. If you need multiple output formats from one source (e.g., PNG to both WebP and AVIF), use `generateFormats: ['webp', 'avif']` instead, which is the recommended approach in current versions of `next-export-optimize-images`.