Skip to main content

Basic Configuration

Default behavior can be changed as needed.
Create export-images.config.js in the root.

* @type {import('next-export-optimize-images').Config}
const config = {
// your configuration values.

module.exports = config

Optional fields


  • Type: string
  • Default: 'out'

Specify if you are customizing the default output directory, such as next export -o outDir.


  • Type: string
  • Default: '_next/static/chunks/images'

You can customize the directory to output optimized images.
The default is '_next/static/chunks/images'.

e.g. If '_optimized' is set.

- out/_next/static/chunks/images/filename.png
+ out/_optimized/filename.png


  • Type: string
  • Default: '_next/static/media'

You can customize the directory to output downloaded external images. The default is '_next/static/media'.


  • Type: number

  • Default: 75

    You can customize the quality of the optimized image.


  • Type: string
  • Default: ''

Required if you have set basePath in next.config.js.
Please set the same value.


  • Type: function
  • Argument: Object
  • Return value: string
KeyTypeDescriptione.g. '/images/sample.png'e.g. require('./sample.png')
pathstringThe path portion./images/_next/static/media
namestringThe file name part.samplesample.{hash}
widthnumberThat image is the resized width.19201920
qualitynumberThe quality specified in the next/image component. Default is 75.7575
extensionstringThe extension of that image.pngpng

You can customize the generation of file names.

e.g. '/images/sample.png'

const config = {
filenameGenerator: ({ path, name, width, quality, extension }) =>
`${path.replace(/^\//, '').replace(/\//g, '-')}-${name}.${width}.${quality}.${extension}`,
- '/images/sample_1920_75.png'
+ 'images-sample.1920.75.png'


When making this setting, make sure that the file names (including the path part) of different images do not cover each other.
Specifically, include the name, width, quality, and extension in the return value. If path is not included, all src's should be specified with import or require so that they can be distinguished by their hash value even if they have the same filename.


  • Type: function
  • Argument: Object
  • Return value: ParsedImageInfo

The argument for this function will be an object with the following shape:

src: string // The source images 'src' attribute
defaultParser: (src: string) => ParsedImageInfo // A function which evaluates the image name, path name (without image name appended and starting w/ '/'), and extension

The return value for this function will be an object with the following shape (ParsedImageInfo type):

pathWithoutName: string // The image path (not including the image name)
name: string // The image name
extension: string // The image extension

This might be useful if any of your images have URLs that do not follow the standard pattern.

For example: Maybe your source image's src attribute is more like, so you might add the following to your config:

NOTE This gets run before filenameGenerator, so the arguments passed into filenameGenerator would be affected by sourceImageParser configuration. (path, name, and extension)

// export-images.config.js
* @type {import('next-export-optimize-images').Config}
const config = {
sourceImageParser: ({ src, defaultParser }) => {
const regExpMatches = src.match(/^.*\?fileId=(.*)&extension=(\w*).*$/)
if (!regExpMatches) {
return defaultParser(src)

// if the src has fileId and extension in its route then it
// must be a non-standard image, so parse it differently for all intents
// and purposes
return {
pathWithoutName: '', // maybe there is no path, or you can supply an arbitrary one for filename processing
name: regExpMatches[1] || '',
extension: regExpMatches[2] || '',


  • Type: Object

You can set optimization options for each extension.
Please refer to the official sharp documentation for more information.


  • Type: Array<Array<Format, Format>>
    Format → "jpeg" | "jpg" | "png" | "webp" | "avif"

It allows you to convert images from any extension to another extension.


const config = {
convertFormat: [
['png', 'webp'],
['jpg', 'avif'],
<Image src="/img.png" width={1280} height={640} alt="" />
<Image src="/img.jpg" width={1280} height={640} alt="" />

The original image will be kept, img.png will be converted to webp format and img.jpg will be converted to avif format and output to the directory.


  • Type: Array<"webp" | "avif">
  • Default: ['webp']

You can generate extra images in extensions specified.

This setting affects the extension displayed in the Picture component.
The order is also important.
For example, if webp is first, then webp will be displayed first.

See Picture component for details.


  • Type: Array<string> | (() => Array<string> | Promise<Array<string>>)

You can directly specify the URL of an external image.
This is useful in cases where it is not known what images will be used for the build using variables, for example.