#Cache

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

• Type: CacheOptions

• Default: production mode is false, development mode is true

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

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

Configure snapshot strategy. Snapshot is used to determine which files have been modified during shutdown. The following configurations are supported:

#snapshot.immutablePaths

• Type: (RegExp | string)[]

• Default: []

An array of paths to immutable files, changes to these paths will be ignored during hot restart.

#snapshot.managedPaths

• Type: (RegExp | string)[]

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

An array of paths managed by the package manager. During hot start, it will determine whether to modify the path based on the version in package.json.

#snapshot.unmanagedPaths

• Type: (RegExp | string)[]

• Default: []

Specifies an array of paths in snapshot.managedPaths that are not managed by the package manager

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