# How to Configure the Cache Directory (`cacheDir`) for Image Optimization in next-export-optimize-images

> Learn to configure the cacheDir for image optimization with next-export-optimize-images. Customize the manifest location in export-images.config.js for better control.

- 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 `cacheDir` option in [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) to specify a custom location for the image optimization manifest, overriding the default `node_modules/.cache/next-export-optimize-images` path.**

The `next-export-optimize-images` library maintains a cache manifest to avoid reprocessing images during static exports. By default, this cache lives inside `node_modules`, but you can configure the cache directory (`cacheDir`) to suit your deployment pipeline or local development workflow as implemented in `dc7290/next-export-optimize-images`.

## Default Cache Location

By default, the library stores processed image metadata in:

```text
node_modules/.cache/next-export-optimize-images

```

This location houses the [`cached-images.json`](https://github.com/dc7290/next-export-optimize-images/blob/main/cached-images.json) manifest, which tracks image hashes and optimization status. While convenient for local development, this default may not persist across CI/CD runs or may conflict with dependency management strategies that prune `node_modules`.

## Configuring a Custom `cacheDir`

To change the cache location, define the `cacheDir` property in your **[`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js)** file at the project root.

### Relative Paths

When you provide a relative path, the library resolves it against the current working directory (`process.cwd()`):

```js
/** @type {import('next-export-optimize-images').Config} */
module.exports = {
  cacheDir: '.next/image-cache',
}

```

This example places the cache adjacent to Next.js's build output, keeping project artifacts organized in one place.

### Absolute Paths

For CI environments or containers with specific volume mounts, use an absolute path:

```js
/** @type {import('next-export-optimize-images').Config} */
module.exports = {
  cacheDir: '/var/cache/next-opt-images',
}

```

Absolute paths are used exactly as specified, bypassing the working directory resolution.

## Internal Implementation Details

According to the source code in `dc7290/next-export-optimize-images`, the `cacheDir` option flows through two primary modules.

### Type Definition in [`src/utils/getConfig.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts)

The configuration interface exposes the optional field in **[`src/utils/getConfig.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts)**:

```ts
/** 
 * You can customize the directory to cache images.
 * The default is 'node_modules/.cache'.
 */
cacheDir?: string

```

This type definition allows both absolute and relative strings, with the default value handled downstream rather than at the type level.

### Path Resolution Logic in [`src/cli/utils/cache.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/cli/utils/cache.ts)

The actual path construction occurs in **[`src/cli/utils/cache.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/cli/utils/cache.ts)**. The module imports the user configuration via `getConfig()` and applies fallback logic:

```ts
const cacheDir = getConfig().cacheDir || 'node_modules/.cache/next-export-optimize-images'

export const defaultCacheDir = cacheDir.startsWith('/')
  ? cacheDir
  : path.join(process.cwd(), cacheDir)

```

Key behaviors:

- **Relative paths**: Joined with `process.cwd()` using `path.join()`
- **Absolute paths**: Used verbatim if they start with `/`
- **Fallback**: Defaults to `node_modules/.cache/next-export-optimize-images` when undefined

The resolved `defaultCacheDir` value drives folder creation via `createCacheDir()` and determines where the manifest file ([`cached-images.json`](https://github.com/dc7290/next-export-optimize-images/blob/main/cached-images.json)) is read or written.

## Practical Use Cases for Custom Cache Directories

Customizing the cache location provides tangible benefits for different environments:

- **CI/CD Persistence**: Point `cacheDir` to a workspace directory (e.g., `/tmp/image-cache` or a mounted volume) to reuse optimized images between build stages without uploading `node_modules`.
- **Monorepo Hygiene**: Isolate caches per application by setting distinct relative paths like `apps/web/.image-cache`, preventing cross-contamination in shared `node_modules`.
- **Disk Management**: Direct large image caches to dedicated storage volumes with abundant space, avoiding bloated `node_modules` folders that slow dependency installs.

## Summary

- The default cache lives in `node_modules/.cache/next-export-optimize-images` as defined in [`src/cli/utils/cache.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/cli/utils/cache.ts).
- Define `cacheDir` in [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) to override the default location.
- Relative paths resolve against `process.cwd()`; absolute paths resolve verbatim.
- The configuration type resides in [`src/utils/getConfig.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/utils/getConfig.ts) and accepts any string path.
- Custom directories enable CI persistence, monorepo isolation, and flexible storage management.

## Frequently Asked Questions

### What happens if I don't specify a `cacheDir`?

If you omit the `cacheDir` option, the library defaults to `node_modules/.cache/next-export-optimize-images`. As implemented in [`src/cli/utils/cache.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/cli/utils/cache.ts), the code falls back to this hardcoded string when `getConfig().cacheDir` returns undefined.

### Can I use environment variables in the `cacheDir` path?

Yes. Since [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) is a standard JavaScript module executed at runtime, you can interpolate environment variables: `cacheDir: process.env.IMAGE_CACHE_DIR || '.next/cache'`. The library receives the resolved string value before checking if it is absolute or relative.

### Does changing the `cacheDir` delete my existing cached images?

No. Changing the directory only affects where future manifests are written. Existing caches in the old location remain untouched, but the library will not recognize them as valid until you move the [`cached-images.json`](https://github.com/dc7290/next-export-optimize-images/blob/main/cached-images.json) file manually or regenerate the cache in the new location.

### Is the `cacheDir` used during both export and development?

The cache directory primarily serves the export optimization CLI. The library reads and writes the [`cached-images.json`](https://github.com/dc7290/next-export-optimize-images/blob/main/cached-images.json) manifest during the static export process defined in [`src/cli/index.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/src/cli/index.ts), which subsequent runs reference to skip redundant image processing.