#Cache

The cache option controls Rspack's caching strategy and lets Rspack reuse cached data across builds to improve build performance.

• Type:

type CacheOptions =
  | boolean
  | { type: 'memory' }
  | {
      type: 'persistent';
      buildDependencies?: string[];
      version?: string;
      portable?: boolean;
      readonly?: boolean;
      snapshot?: {
        immutablePaths?: Array<string | RegExp>;
        unmanagedPaths?: Array<string | RegExp>;
        managedPaths?: Array<string | RegExp>;
      };
      storage?: {
        type: 'filesystem';
        directory?: string;
        maxAge?: number;
        maxGenerations?: number;
      };
    };

• Default: { type: 'memory' } in development mode (equivalent to true), false in production mode and none mode

#Memory cache

Set cache to true or { type: 'memory' } to enable in-memory cache. Memory cache is kept only in the current compiler process and is useful for rebuilds, watch mode, and HMR.

Memory cache does not write cache data to disk, so it is cleared when the process exits and cannot speed up a fresh build started later. It is best suited for long-running development workflows where the same compiler instance handles multiple rebuilds.

export default {
  cache: true,
};

or:

export default {
  cache: {
    type: 'memory',
  },
};

#Persistent cache

Set cache to { type: 'persistent' } to enable persistent cache. Persistent cache stores cache data on disk so later build processes can reuse it.

export default {
  cache: {
    type: 'persistent',
  },
};

#buildDependencies

• Type: string[]
• Default: []

cache.buildDependencies is an array of file or directory paths treated as build dependencies. Rspack tracks these paths and invalidates the persistent cache when any tracked build dependency changes.

import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

export default {
  cache: {
    type: 'persistent',
    buildDependencies: [__filename, join(__dirname, './tsconfig.json')],
  },
};

#version

• Type: string
• Default: ""

cache.version is an additional version string included in the persistent cache key. Use it to manually isolate or invalidate persistent cache data.

export default {
  cache: {
    type: 'persistent',
    version: 'v1',
  },
};

#portable

• Type: boolean
• Default: false

Enable portable cache mode. When enabled, the generated cache content can be shared across different platforms and paths within the same project.

Portable cache is built on top of persistent cache and makes the cache platform-independent by converting platform-specific data (e.g., absolute paths to relative paths) during serialization and deserialization.

Example:

export default {
  cache: {
    type: 'persistent',
    portable: true,
  },
};

#readonly

• Type: boolean
• Default: false

Enable read-only cache mode. When enabled, the cache will only be read from disk and never written to, which is useful for CI environments where you want to use a pre-warmed cache without modifying it.

Example:

Enable only in CI:

export default {
  cache: {
    type: 'persistent',
    // Make sure your CI environment sets `process.env.CI` (or a similar env variable)
    readonly: Boolean(process.env.CI),
  },
};

#snapshot

• Type: object
• Default: { immutablePaths: [], managedPaths: [/[\\/]node_modules[\\/][^.]/], unmanagedPaths: [] }

Configure the snapshot strategy used by persistent cache to determine which dependencies have changed since the previous build.

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};

#snapshot.immutablePaths

• Type: (RegExp | string)[]
• Default: []

An array of immutable paths. When restoring from persistent cache, Rspack treats matching paths as unchanged and does not re-check their contents. This is suitable for content-addressed paths that never change after being written.

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      immutablePaths: [/[\\/]\.yarn[\\/]cache[\\/]/],
    },
  },
};

#snapshot.managedPaths

• Type: (RegExp | string)[]
• Default: [/[\\/]node_modules[\\/][^.]/]

An array of paths managed by the package manager. When restoring from persistent cache, Rspack uses the version field in the corresponding package.json to determine whether a package has changed, instead of hashing file contents. This speeds up cache validation for packages that are only updated through the package manager.

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};

#snapshot.unmanagedPaths

• Type: (RegExp | string)[]
• Default: []

Specifies paths within cache.snapshot.managedPaths that should not be treated as managed by the package manager. Files in these paths fall back to content-hash-based cache validation.

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      unmanagedPaths: [/[\\/]node_modules[\\/]my-linked-package[\\/]/],
    },
  },
};

#storage

• Type: { type: 'filesystem'; directory?: string; maxAge?: number; maxGenerations?: number }

Configure cache storage. Currently only filesystem storage is supported.

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      maxAge: 7 * 24 * 60 * 60,
      maxGenerations: 10,
    },
  },
};

#storage.type

• Type: 'filesystem'
• Default: 'filesystem'

Use type to configure the cache storage type. Currently only filesystem storage is supported.

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
    },
  },
};

#storage.directory

• Type: string
• Default: node_modules/.cache/rspack/<mode> or node_modules/.cache/rspack/<name>-<mode>

Use directory to configure the cache directory. The default directory is resolved from config.context, config.name, config.mode, and the multi-compiler index. In multi-compiler mode, later compilers append -<index> to avoid sharing the same directory.

export default {
  cache: {
    type: 'persistent',
    storage: {
      directory: '.rspack-cache',
    },
  },
};

#storage.maxAge

• Type: number (positive integer, in seconds) or Infinity
• Default: 7 * 24 * 60 * 60 (7 days)

The maximum time, in seconds, that a cache generation can remain unused. During cleanup, Rspack removes cache generations that have not been accessed for longer than maxAge. Set maxAge to Infinity to disable age-based cleanup.

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      maxAge: 7 * 24 * 60 * 60,
    },
  },
};

#storage.maxGenerations

• Type: number (positive integer) or Infinity
• Default: 3

This is a generational cleanup policy that controls how many cache generations can be retained in the current cache directory. When the number of generations exceeds the limit, Rspack removes old inactive generations. Set maxGenerations to Infinity to disable generation-based cleanup.

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      maxGenerations: 10,
    },
  },
};

#Inspect persistent cache logs

Persistent cache logs are emitted through the rspack.persistentCache logger. To display them in the build stats, enable this logger with stats.loggingDebug:

export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: false,
    loggingDebug: /^rspack\.persistentCache$/,
  },
};

The logs include key persistent cache events, such as whether persistent cache is enabled, whether build dependencies are valid, whether cache recovery succeeded, and why the persistent cache was invalidated. They also include read and write timings for each cache phase (for example, build dependency validation, snapshot restore, occasion recovery, staging, and flushing to disk).

If you want to include logs from other loggers too, enable stats.logging:

export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: 'info',
    loggingDebug: /^rspack\.persistentCache$/,
  },
};

#Disable cache

Set cache to false to disable both memory cache and persistent cache. Disabling cache is generally not recommended because it can make rebuilds during development significantly slower.

export default {
  cache: false,
};

#Migrating from webpack

See Migrate from webpack - Cache configuration for how to migrate webpack cache configuration to Rspack.