#performance.buildCache

• Type:

type BuildCacheConfig =
  | boolean
  | {
      cacheDirectory?: string;
      cacheDigest?: Array<string | undefined>;
      buildDependencies?: string[];
    };

• Default: false
• Version: >= 1.2.5

To enable or configure persistent build cache.

When enabled, Rspack will store the build snapshots in the cache directory. In subsequent builds, if the cache is hit, Rspack can reuse the cached results instead of rebuilding from scratch, which can reduce the build time.

#Enable cache

Setting performance.buildCache to true will enable the persistent build cache:

export default {
  performance: {
    buildCache: true,
  },
};

Or only enable cache in development mode:

const isDev = process.env.NODE_ENV === 'development';

export default {
  performance: {
    buildCache: isDev,
  },
};

#Options

#cacheDirectory

• Type: string
• Default: <root>/node_modules/.cache/rspack

Set the directory for cache files. Relative paths are resolved from the project root.

import path from 'node:path';

export default {
  performance: {
    buildCache: {
      cacheDirectory: path.resolve(__dirname, 'node_modules/.my-cache'),
    },
  },
};

#cacheDigest

• Type: Array<string | undefined>
• Default: undefined

Add additional cache digests, the previous build cache will be invalidated when any value in the array changes.

cacheDigest allows you to add variables that affect the build result, for example process.env.SOME_ENV.

export default {
  performance: {
    buildCache: {
      cacheDigest: [process.env.SOME_ENV],
    },
  },
};

#buildDependencies

• Type: string[]

buildDependencies is an array of additional code dependencies for the build. Rspack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.

Equivalent to Rspack's cache.buildDependencies option.

#Default value

Rsbuild will use the following configuration files as the default build dependencies:

• package.json
• The file selected by source.tsconfigPath
• The .env files loaded by Rsbuild, when automatic env loading is enabled
• .browserslistrc
• tailwind.config.*

Additionally:

• When using Rsbuild CLI, it will also automatically add the Rsbuild configuration file (rsbuild.config.*) to the build dependencies.
• When using Rsbuild's loadConfig JS API, it will also automatically add the configuration file path to the build dependencies.

#Example

When you add other build dependencies, Rsbuild merges these custom dependencies with the default dependencies and passes them to Rspack.

export default {
  performance: {
    buildCache: {
      buildDependencies: [__filename],
    },
  },
};

#View cache statistics

Use the onAfterEnvironmentCompile hook to read cache statistics after each compilation and check whether cached results are being reused.

This requires Rsbuild >= 2.3.0. Enable the experimental experiments.newCache option:

import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  performance: {
    buildCache: true,
  },
  tools: {
    rspack: {
      experiments: {
        newCache: true,
      },
    },
  },
  plugins: [
    {
      name: 'cache-statistics',
      setup(api) {
        api.onAfterEnvironmentCompile(({ stats, environment }) => {
          const cacheInfo = stats?.toJson({
            all: false,
            cacheInfo: true,
          }).cacheInfo;

          if (cacheInfo) {
            console.log(`Cache statistics (${environment.name})`);
            console.table(cacheInfo);
          }
        });
      },
    },
  ],
});

For the meaning of each field, see Rspack's cacheInfo documentation.