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

To convert PNG images to WebP during static export, add a convertFormat array to your 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, the TypeScript definition declares the field as:

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, 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 (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 file in the project root.

Basic Configuration Example

To convert all PNG files to WebP format during export:

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

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:

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

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 as an array of [source, target] tuples to enable automatic format conversion during next export.
• Valid formats defined in src/utils/formatValidate.ts include jpeg, jpg, png, webp, and avif.
• The conversion logic in 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. 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 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.

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