#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';
      name?: string;
      buildDependencies?: string[];
      version?: string;
      maxAge?: number;
      maxVersions?: number;
      portable?: boolean;
      readonly?: boolean;
      snapshot?: {
        immutablePaths?: Array<string | RegExp>;
        unmanagedPaths?: Array<string | RegExp>;
        managedPaths?: Array<string | RegExp>;
      };
      storage?: {
        type: 'filesystem';
        directory?: string;
        location?: string;
      };
    };

• 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',
  },
};

#name

• Type: string
• Default: <config.name>-<mode> when config.name is set, otherwise <mode>

cache.name names a persistent cache. Different names create coexisting caches. In multi-compiler mode, the first compiler keeps the default name, while later compilers append their zero-based index, such as -1 and -2.

export default {
  cache: {
    type: 'persistent',
    name: 'client-development',
  },
};

#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 identifies the format of the persistent cache data. When it differs from the stored version, Rspack does not reuse the existing cache and overwrites its content after the build. Update it when configuration changes make the existing cache incompatible.

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

#maxVersions

• Type: number
• Default: Not set

cache.maxVersions is retained for backward compatibility but has no effect. Rspack keeps only one persistent cache per compilerPath. Explicitly configuring this option emits a deprecation warning.

#maxAge

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

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

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

#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; location?: string }

Configure cache storage. Currently only filesystem storage is supported.

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

#storage.type

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

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

#storage.directory

• Type: string
• Default: node_modules/.cache/rspack

cache.storage.directory is the base directory for persistent caches, matching the semantics of webpack's cache.cacheDirectory. Relative paths are resolved from config.context.

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

#storage.location

• Type: string
• Default: <storage.directory>/<cache.name>

cache.storage.location is the complete path where Rspack reads and writes cache data, matching the semantics of webpack's cache.cacheLocation. When omitted, Rspack derives it from cache.storage.directory and cache.name. Relative paths are resolved from config.context.

export default {
  context: '/project',
  cache: {
    type: 'persistent',
    name: 'client',
    storage: {
      type: 'filesystem',
      directory: '.rspack-cache',
    },
  },
};

// cache.storage.location defaults to '/project/.rspack-cache/client'.

Set storage.location explicitly to override the derived path:

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      location: '.custom-cache/client',
    },
  },
};

#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.