How to Use `generateFormats` to Create Multiple Image Formats (WebP, AVIF) in Next.js

Set generateFormats: ['webp', 'avif'] in your export-images.config.js file, and the next-export-optimize-images library will automatically generate optimized versions and serve them via the <Picture> component for automatic browser selection.

The generateFormats configuration option in next-export-optimize-images enables automatic generation of modern image formats alongside your original assets. This feature eliminates manual conversion work while ensuring browsers receive the smallest possible file size through native format negotiation.

What is generateFormats?

generateFormats is a configuration array that instructs the build system to create additional optimized copies of your images in the specified formats. According to the source code in src/utils/getConfig.ts (lines 86-94), this option accepts an array of image format strings that the library supports during the export process.

When configured, the library processes each source image through the build pipeline defined in src/utils/buildOutputInfo.ts (lines 66-70), which merges your specified formats with the original file extension to determine the complete output set.

Configuration Setup

Basic WebP and AVIF Configuration

To generate both WebP and AVIF versions of your images, create or modify your export-images.config.js file:

// export-images.config.js
/** @type {import('next-export-optimize-images').Config} */
module.exports = {
  generateFormats: ['webp', 'avif'],
};

This configuration produces three files for an input named photo.jpg:

• /_next/static/chunks/images/photo_800.webp
• /_next/static/chunks/images/photo_800.avif
• /_next/static/chunks/images/photo_800.jpg (original fallback)

Controlling Format Priority

The array order defines priority for the <source> tags rendered by the <Picture> component. To prioritize AVIF over WebP, reverse the order:

module.exports = {
  generateFormats: ['avif', 'webp'],
};

As implemented in src/components/client/picture.tsx (lines 22-35), the component generates <source> elements in the exact order specified. Browsers scan these top-to-bottom and load the first format they support, meaning AVIF-capable browsers will use AVIF while older browsers fall back to WebP or the original JPEG/PNG.

Single Format Generation

You can generate only one additional format if preferred:

module.exports = {
  generateFormats: ['avif'],
};

This creates only the AVIF variant, reducing build output size while still delivering modern compression to supported browsers.

How It Works Under the Hood

Build-Time Processing

During the static export, the function buildOutputInfo in src/utils/buildOutputInfo.ts iterates through your generateFormats array and appends each extension to the output manifest. The system runs each image through the optimization pipeline once per format, applying format-specific encoders to generate the compressed variants.

Runtime Component Behavior

The <Picture> component exported from next-export-optimize-images/picture automatically reads your generateFormats configuration at runtime. As shown in src/components/client/picture.tsx, it dynamically constructs a <picture> element containing:

• One <source> tag per generated format with the appropriate type attribute
• The standard <Image> component as the final fallback

This approach leverages native browser content negotiation without requiring JavaScript feature detection.

Implementing the Picture Component

No additional props are required to enable format switching. Import and use the component exactly as you would use the standard Next.js Image component:

import Picture from 'next-export-optimize-images/picture';

export default function Gallery() {
  return (
    <div>
      <Picture
        src="/images/photo.jpg"
        width={800}
        height={600}
        alt="Sample description"
      />
    </div>
  );
}

The component queries the internal configuration context established in src/utils/getConfig.ts and renders the appropriate <source> tags automatically.

Summary

• generateFormats is defined in export-images.config.js as an array of format strings like ['webp', 'avif'].
• Build logic in src/utils/buildOutputInfo.ts creates output files for each format specified.
• Array order determines <source> tag priority in the generated HTML, with the first format preferred by browsers.
• The <Picture> component in src/components/client/picture.tsx handles automatic format negotiation without manual intervention.
• Original images are always preserved as fallbacks for browsers that support neither specified format.

Frequently Asked Questions

What image formats does generateFormats support?

The library supports WebP and AVIF as primary modern formats, alongside the original JPEG, PNG, or GIF formats. You can specify any combination of these in the array, though WebP and AVIF offer the best compression-to-quality ratios for most use cases.

How does the browser choose which format to load?

The browser evaluates the <source> elements inside the <picture> tag in the order they appear in the DOM. It loads the first format where the type attribute matches a supported MIME type. As implemented in src/components/client/picture.tsx, the component lists formats in the exact order defined in your generateFormats array, giving you full control over priority.

Can I use generateFormats with the standard Next.js Image component?

No, format generation requires the <Picture> component from next-export-optimize-images/picture. The standard Next.js <Image> component does not render multiple <source> tags or handle the format manifest created during the build process. You must import the specialized component to benefit from automatic format selection.

Does generateFormats increase build time significantly?

Yes, build time scales linearly with the number of formats specified. Each additional format requires the build system to re-encode the entire image set. For a site with thousands of images, generating both WebP and AVIF will approximately triple the image processing duration compared to generating original formats alone, though the resulting file size savings typically justify the tradeoff for production builds.

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