docs: add performance.buildCache configuration

packages/core/src/types/config.ts

@@ -456,10 +456,17 @@ export type NormalizedSecurityConfig = Required<SecurityConfig>;
 
 export type ConsoleType = 'log' | 'info' | 'warn' | 'error' | 'table' | 'group';
 
-// may extends cache options in the futures
 export type BuildCacheOptions = {
-  /** Base directory for the filesystem cache. */
+  /**
+   * The output directory of the cache files.
+   * @default 'node_modules/.cache'
+   */
   cacheDirectory?: string;
+  /**
+   * Add additional cache digests, the previous build cache will be invalidated
+   * when any value in the array changes.
+   * @default undefined
+   */
   cacheDigest?: Array<string | undefined>;
 };
 
@@ -548,7 +555,8 @@ export interface PerformanceConfig {
   removeMomentLocale?: boolean;
 
   /**
-   * Controls the Rsbuild's caching behavior during the build process.
+   * To enable or configure persistent build cache.
+   * @experimental This feature is experimental and may be changed in the future.
    */
   buildCache?: BuildCacheOptions | boolean;
 

website/docs/en/config/performance/build-cache.mdx

@@ -0,0 +1,89 @@
+# performance.buildCache
+
+- **Type:**
+
+```ts
+type BuildCacheConfig =
+  | boolean
+  | {
+      cacheDirectory?: string;
+      cacheDigest?: Array<string | undefined>;
+    };
+```
+
+- **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.
+
+:::tip
+
+Rspack's persistent cache is [experimental](https://rspack.dev/config/experiments#experimentscache) and may change in the future.
+
+:::
+
+## Enable cache
+
+Setting `performance.buildCache` to `true` will enable the persistent build cache:
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  performance: {
+    buildCache: true,
+  },
+});
+```
+
+Or only enable cache in development mode:
+
+```ts title="rsbuild.config.ts"
+const isDev = process.env.NODE_ENV === 'development';
+
+export default defineConfig({
+  performance: {
+    buildCache: isDev,
+  },
+});
+```
+
+## Options
+
+### cacheDirectory
+
+- **Type:** `string`
+- **Default:** `node_modules/.cache`
+
+Set the output directory of the cache files.
+
+```ts title="rsbuild.config.ts"
+import path from 'node:path';
+
+export default defineConfig({
+  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` can be used to add some variables that will affect the build result, for example `process.env.SOME_ENV`.
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  performance: {
+    buildCache: {
+      cacheDigest: [process.env.SOME_ENV],
+    },
+  },
+});
+```

website/docs/en/guide/optimization/build-performance.mdx

@@ -14,6 +14,10 @@ Please refer to the [Performance Building Analysis](/guide/debug/build-profiling
 
 The following are some general optimization methods, which can speed up the development build and production build.
 
+### Enable persistent cache
+
+Rsbuild provides [performance.buildCache](/config/performance/build-cache) configuration, which can significantly improve the speed of rebuilding.
+
 ### Reducing modules
 
 Optimizing the number of modules referenced by the application can reduce the bundle size and improve build performance. Please read the [Bundle Size Optimization](/guide/optimization/optimize-bundle) section to learn some optimization methods.

website/docs/zh/config/performance/build-cache.mdx

@@ -0,0 +1,89 @@
+# performance.buildCache
+
+- **类型：**
+
+```ts
+type BuildCacheConfig =
+  | boolean
+  | {
+      cacheDirectory?: string;
+      cacheDigest?: Array<string | undefined>;
+    };
+```
+
+- **默认值：** `false`
+- **版本：** `>= 1.2.5`
+
+用于启用或配置持久化构建缓存。
+
+当启用时，Rspack 会在缓存目录中存储构建快照。在后续的构建中，如果命中缓存，Rspack 可以重用缓存的结果，而不是从头开始重新构建，这可以显著减少构建时间。
+
+:::tip
+
+Rspack 的持久化缓存处于 [实验性阶段](https://rspack.dev/zh/config/experiments#experimentscache)，可能会在未来的版本中发生变化。
+
+:::
+
+## 启用缓存
+
+设置 `performance.buildCache` 为 `true` 将启用持久化构建缓存：
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  performance: {
+    buildCache: true,
+  },
+});
+```
+
+或者仅在开发模式下启用缓存：
+
+```ts title="rsbuild.config.ts"
+const isDev = process.env.NODE_ENV === 'development';
+
+export default defineConfig({
+  performance: {
+    buildCache: isDev,
+  },
+});
+```
+
+## 选项
+
+### cacheDirectory
+
+- **类型：** `string`
+- **默认值：** `node_modules/.cache`
+
+用于设置缓存文件的输出目录。
+
+```ts title="rsbuild.config.ts"
+import path from 'node:path';
+
+export default defineConfig({
+  performance: {
+    buildCache: {
+      cacheDirectory: path.resolve(__dirname, 'node_modules/.my-cache'),
+    },
+  },
+});
+```
+
+### cacheDigest
+
+- **类型：** `Array<string | undefined>`
+- **默认值：** `undefined`
+
+添加额外的缓存摘要，当数组中的任何值发生变化时，之前的构建缓存就会失效。
+
+`cacheDigest` 可以用于添加一些会对构建结果产生影响的变量，例如 `process.env.SOME_ENV`。
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  performance: {
+    buildCache: {
+      cacheDigest: [process.env.SOME_ENV],
+    },
+  },
+});
+```

website/docs/zh/guide/optimization/build-performance.mdx

@@ -14,6 +14,10 @@ Rsbuild 默认对构建性能进行了充分优化，但是随着使用场景变
 
 以下是一些通用的优化方法，对开发模式和生产模式均有提速效果。
 
+### 开启持久化缓存
+
+Rsbuild 提供了 [performance.buildCache](/config/performance/build-cache) 配置，开启后可以显著提升重构建的速度。
+
 ### 减少模块
 
 对应用引用的模块数量进行优化，可以减少产物体积并提升构建性能，请阅读 [优化产物体积](/guide/optimization/optimize-bundle) 章节来了解一些优化方法。