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

Set the cacheDir option in 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:

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

This location houses the 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 file at the project root.

Relative Paths

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

/** @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:

/** @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

The configuration interface exposes the optional field in src/utils/getConfig.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

The actual path construction occurs in src/cli/utils/cache.ts. The module imports the user configuration via getConfig() and applies fallback logic:

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) 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.
• Define cacheDir in 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 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, 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 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 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 manifest during the static export process defined in src/cli/index.ts, which subsequent runs reference to skip redundant image processing.

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