How to Specify a Directory for Downloaded External Images in next-export-optimize-images

Set the externalImageDir option in your export-images.config.js file to define a custom relative path where external images are stored during the static export process.

When using next-export-optimize-images to handle remote assets during a static Next.js export, you need control over where downloaded files land in your file system. The library provides the externalImageDir configuration option to customize this destination, reading your preference from the export-images.config.js file and applying it throughout the build pipeline from configuration parsing to file writing.

Configuring the externalImageDir Option

To specify a custom directory, add the externalImageDir field to your configuration file. The value should be a relative path from your project root.

// export-images.config.js
module.exports = {
  externalImageDir: 'public/assets/external',
  // ... other configuration options
};

The library sanitizes this value internally by stripping leading and trailing slashes, so public/assets/external and /public/assets/external/ resolve identically.

How the Custom Directory Is Applied During Export

The configuration flows through three distinct stages in the source code to ensure external images land in the correct location.

Configuration Schema Validation

In src/utils/getConfig.ts (lines 45-51), the library defines the externalImageDir option within the configuration schema. This code handles the parsing and sanitization, removing surrounding slashes to ensure consistent path construction and preventing empty string values from causing path errors.

Manifest Generation

During the manifest build step in src/cli/index.ts (lines 200-210), the code constructs the final source URL for each external image. It prefixes the sanitized externalImageDir value—or falls back to the default _next/static/media if the option is undefined—and appends a hash-based filename to prevent collisions.

File Download and Storage

The externalImagesDownloader function in src/cli/external-images/index.ts (lines 21-48) receives the resolved directory via the destDir argument. It writes each downloaded file using path.join(destDir, src), ensuring external assets land in your specified folder rather than the default location.

Practical Implementation Example

Here is a complete workflow showing the configuration and resulting output structure.

First, define your custom directory in the configuration file:

// export-images.config.js
module.exports = {
  externalImageDir: 'public/images/cdn',
};

Execute the CLI command to process your external images:

npx next-export-optimize-images

The generated manifest entries will reflect your custom path:

{
  "output": "public/images/cdn/a1b2c3d4.jpg",
  "src": "/public/images/cdn/a1b2c3d4.jpg",
  "width": 800,
  "extension": "jpg",
  "externalUrl": "https://cdn.example.com/photo.jpg"
}

The downloader then writes the actual file to public/images/cdn/a1b2c3d4.jpg relative to your project root.

Summary

• Add externalImageDir to export-images.config.js to override the default _next/static/media path.
• The library sanitizes your input by removing leading and trailing slashes automatically in src/utils/getConfig.ts.
• The value is applied to manifest paths in src/cli/index.ts and used for disk writes in src/cli/external-images/index.ts.
• Specify a relative path from your project root; the library handles the directory resolution during the build process.

Frequently Asked Questions

What is the default directory for external images in next-export-optimize-images?

If you omit the externalImageDir option, the library defaults to _next/static/media. This fallback is applied during manifest generation in src/cli/index.ts when no custom value is present in the configuration object.

Can I use an absolute path for externalImageDir?

No, the library expects a relative path from your project root. While the code sanitizes leading and trailing slashes in src/utils/getConfig.ts, using absolute paths may cause unexpected behavior since the final write operation in src/cli/external-images/index.ts uses path.join(destDir, src) relative to the build context.

How does the library handle filename collisions for external images?

The library generates hash-based filenames during manifest creation (lines 200-210 in src/cli/index.ts). This ensures that even if multiple external images share the same original filename, they receive unique hashed names in your specified externalImageDir, preventing overwrites.

Do I need to create the directory manually before running the export?

No, the downloader logic in src/cli/external-images/index.ts handles the file writing process. As long as the parent directories exist or your environment allows directory creation, the library will write files to the specified path. However, ensure your externalImageDir points to a location within your project structure that Next.js can serve statically.

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