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

> Learn how to set the externalImageDir option in your export-images.config.js to specify a custom directory for downloaded external images during your next export.

- Repository: [d-suke/next-export-optimize-images](https://github.com/dc7290/next-export-optimize-images)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Set the `externalImageDir` option in your [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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.

```javascript
// 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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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:

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

```

Execute the CLI command to process your external images:

```bash
npx next-export-optimize-images

```

The generated manifest entries will reflect your custom path:

```json
{
  "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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts).
- The value is applied to manifest paths in [`src/cli/index.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/cli/index.ts) and used for disk writes in [`src/cli/external-images/index.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts), using absolute paths may cause unexpected behavior since the final write operation in [`src/cli/external-images/index.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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.