How to Customize the Output Directory for Optimized Images in next-export-optimize-images

Set the imageDir option in your export-images.config.js file to define a custom subdirectory (relative to outDir) where the plugin writes all optimized image files.

The next-export-optimize-images library generates optimized image variants during Next.js static export. By default, these assets are stored in _next/static/chunks/images, but you can relocate them using the imageDir configuration option. This article explains how to customize the output directory based on the source code implementation in the dc7290/next-export-optimize-images repository.

Understanding the imageDir Configuration Option

The imageDir setting controls the destination folder for processed images. According to src/utils/getConfig.ts, the default value is '_next/static/chunks/images'.

During the build pipeline, src/utils/buildOutputInfo.ts consumes this configuration to construct final output paths. At lines 62-64, the code normalizes the path by stripping leading and trailing slashes:

const outputDir = `/${
  config.imageDir ? config.imageDir.replace(/^\//, '').replace(/\/$/, '')
                : '_next/static/chunks/images'
}`

The resulting outputDir is then joined with the filename at line 75:

const output = `${outputDir}/${filename.replace(/^\//, '')}`

This ensures consistent path formatting regardless of how you define the directory string.

Configuring a Custom imageDir

To override the default location, create or modify export-images.config.js in your project root. The library automatically loads this file via getConfig() in src/utils/getConfig.ts.

Basic Custom Directory

Set the imageDir property to your preferred relative path:

// export-images.config.js
/**
 * @type {import('next-export-optimize-images').Config}
 */
module.exports = {
  imageDir: '_optimized',
}

With this configuration and the default outDir (out), your export produces:

out/
 └─ _optimized/
      ├─ logo_800.webp
      ├─ hero_1200.avif
      └─ ...

Compared to the default structure:

out/
 └─ _next/
      └─ static/
           └─ chunks/
                └─ images/
                     ├─ logo_800.webp
                     └─ ...

Combining imageDir with outDir

The imageDir path resolves as a subdirectory within your outDir folder. When both options are configured in export-images.config.js, the plugin nests the image directory accordingly.

// export-images.config.js
module.exports = {
  outDir: 'dist',
  imageDir: 'assets/images',
}

Running next export generates this structure:

dist/
 └─ assets/
      └─ images/
           ├─ avatar_400.webp
           └─ ...

Path Normalization Behavior

The implementation in src/utils/buildOutputInfo.ts handles formatting inconsistencies automatically. Leading and trailing slashes are stripped via regex replacement, so the following configurations produce identical results:

module.exports = {
  imageDir: '/media/',   // Normalized to /media
}

// Equivalent to:
module.exports = {
  imageDir: 'media',     // Also results in /media
}

You do not need to manually sanitize path strings before setting this option.

Summary

• The imageDir option in export-images.config.js controls where optimized images are stored relative to the outDir directory
• Default location is '_next/static/chunks/images' as defined in src/utils/buildOutputInfo.ts
• Path normalization automatically removes leading and trailing slashes at lines 62-64 of buildOutputInfo.ts
• The setting combines with outDir to create nested output structures during static export
• Changes take effect immediately when running next export or next build in export mode

Frequently Asked Questions

What is the default output directory for optimized images?

The default imageDir value is '_next/static/chunks/images'. As implemented in src/utils/buildOutputInfo.ts, this places all optimized image files inside the _next/static/chunks/images subdirectory relative to your export output folder.

Can I use absolute paths for the imageDir setting?

No, imageDir accepts relative paths only. The plugin resolves these paths inside your configured outDir directory. Any leading slashes are automatically removed by the regex replacement logic in src/utils/buildOutputInfo.ts lines 62-64.

How does imageDir interact with the outDir configuration option?

The imageDir path resolves as a subdirectory within outDir. If you configure outDir: 'dist' and imageDir: 'assets', the plugin writes optimized images to dist/assets/. This relationship is established when getConfig() loads both values from your configuration file.

Do I need to create the imageDir folder manually before exporting?

No. The plugin automatically creates the necessary directory hierarchy during the export process. The buildOutputInfo.ts utility generates output paths and ensures parent directories exist when writing optimized image files to disk.

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