#Cache

Rspack caches snapshots and intermediate build artifacts, then reuses them in subsequent builds to improve build speed.

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

• Default: true in development mode, false in production mode and none mode

#Disable cache

Configuring cache to false to disable cache.

export default {
  cache: false,
};

#Memory cache

Configuring cache to true or { type: "memory" } to enable memory cache.

export default {
  cache: true,
};

or

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

#Persistent cache

Configuring cache to { type: "persistent" } to enable persistent cache.

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

#cache.buildDependencies

• Type: string[]

• Default: []

cache.buildDependencies is an array of files containing build dependencies, Rspack will use the hash of each of these files to invalidate the persistent cache.

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

#cache.version

• Type: string

• Default: ""

Cache versions, different versions of caches are isolated from each other.

#cache.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,
  },
};

#cache.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),
  },
};

#cache.snapshot

• Type: object

• Default: {}

Configure snapshot strategy. Snapshot is used to determine which files have been modified since the last build. The following configurations are supported:

#snapshot.immutablePaths

• Type: (RegExp | string)[]

• Default: []

An array of paths to immutable files. On hot restart, changes to these paths will be ignored and the cache will be considered valid without re-checking file contents. Suitable for content-addressed paths that are guaranteed to never change once written.

#snapshot.managedPaths

• Type: (RegExp | string)[]

• Default: [/[\\/]node_modules[\\/][^.]/]

An array of paths managed by the package manager. On hot restart, Rspack will use 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 via the package manager.

#snapshot.unmanagedPaths

• Type: (RegExp | string)[]

• Default: []

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

#cache.storage

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

• Default: { type: 'filesystem', directory: 'node_modules/.cache/rspack' }

Configure cache storage. Currently only file system storage is supported. The cache directory can be set through directory. The default is node_modules/.cache/rspack.

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

#Migrating from webpack config

The Rspack cache configuration is different from the webpack cache configuration. You can refer to the following steps to migrate the webpack cache configuration.

1. According to the cache type, set the Rspack cache type. Continue with the next step for persistent cache, and stop here for other types of cache.

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

2. Migrate cache.buildDependencies

export default {
- cache: {
-   buildDependencies: {
-     config: [__filename, path.join(__dirname, "package.json")],
-     ts: [path.join(__dirname, "tsconfig.json")]
-   }
- },
+ cache: {
+   type: "persistent",
+   buildDependencies: [
+     __filename,
+     path.join(__dirname, "package.json"),
+     path.join(__dirname, "tsconfig.json")
+   ]
+ },
};

3. Migrate cache.version and cache.name

export default {
- cache: {
-   name: `${config.name}-${config.mode}-${otherFlags}`,
-   version: appVersion
- },
+ cache: {
+   type: "persistent",
+   version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
+ },
};

4. Migrate snapshot

export default {
- snapshot: {
-   immutablePaths: [path.join(__dirname, "constant")],
-   managedPaths: [path.join(__dirname, "node_modules")],
-   unmanagedPaths: []
- },
+ cache: {
+   type: "persistent",
+   snapshot: {
+     immutablePaths: [path.join(__dirname, "constant")],
+     managedPaths: [path.join(__dirname, "node_modules")],
+     unmanagedPaths: []
+   }
+ },
};

5. Migrate cache.cacheDirectory

export default {
- cache: {
-   cacheDirectory: path.join(__dirname, "node_modules/.cache/test")
- },
+ cache: {
+   type: "persistent",
+   storage: {
+     type: "filesystem",
+     directory: path.join(__dirname, "node_modules/.cache/test")
+   }
+ },
};

Sample migration code:

function transform(webpackConfig, rspackConfig) {
  if (webpackConfig.cache === undefined) {
    webpackConfig.cache = webpackConfig.mode === 'development';
  }
  // 1. if using disable cache, just set `cache` = false
  if (!webpackConfig.cache) {
    rspackConfig.cache = false;
    return;
  }
  // 2. if using memory cache, just set `cache` = true
  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
    rspackConfig.cache = true;
    return;
  }
  // 3. using persistent cache, set `cache` = { type: "persistent" }
  rspackConfig.cache = { type: 'persistent' };
  // 4. building `cache` from webpack config
  rspackConfig.cache.buildDependencies = Object.values(
    webpackConfig.cache.buildDependencies || {},
  ).flat();
  rspackConfig.cache.version = [
    webpackConfig.cache.name,
    webpackConfig.cache.version,
  ].join();
  rspackConfig.cache.snapshot = {
    immutablePaths: webpackConfig.snapshot?.immutablePaths,
    managedPaths: webpackConfig.snapshot?.managedPaths,
    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
  };
  rspackConfig.cache.storage = {
    type: 'filesystem',
    directory: webpackConfig.cache?.cacheDirectory,
  };
}