docs: add persistent cache migration (#8978)

* docs: add persistent cache migration * fix: comment * fix: comment
web-infra-dev · Jan 13, 2025 · f6210c1 · f6210c1
1 parent fa3e453
commit f6210c1
Show file tree

Hide file tree

Showing 2 changed files with 306 additions and 4 deletions.
diff --git a/website/docs/en/config/experiments.mdx b/website/docs/en/config/experiments.mdx
@@ -366,11 +366,15 @@ type ExperimentCacheOptions =
     };
 ```
 
-Control experimental caching behavior. This will only work if [global cache](/config/cache) is set to `true`.
+Control experimental caching behavior. This will only work if [config.cache](/config/cache) is set to `true`.
+
+:::info title="Note"
+In production mode, the default value of `config.cache` is `false`, which will cause this configuration item invalid. It is recommended to directly configure `config.cache` to `true`.
+:::
 
 ### Disable cache
 
-Configuring `experiment.cache` to `false` to disable cache, which is no different from configuring the [global cache](/config/cache) to `false`.
+Configuring `experiment.cache` to `false` to disable cache, which is no different from configuring the [config.cache](/config/cache) to `false`.
 
 ```js title="rspack.config.js"
 module.exports = {
@@ -500,3 +504,150 @@ module.exports = {
   },
 };
 ```
+
+:::tip
+Rspack will generate a cache folder in the `storage.directory` based on [config.name](/config/other-options#name), [config.mode](/config/mode#mode), the file contents in [buildDependencies](#cachebuilddependencies) and [version](#cacheversion).
+
+Rspack will automatically clean up cache folders that have not been accessed for a long time (7 days) at startup.
+:::
+
+### 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.
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   type: 'filesystem',
+- },
++ cache: true,
++ experiments: {
++   cache: {
++     type: 'persistent',
++   },
++ },
+};
+```
+
+2. Migrate `cache.buildDependencies`
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   buildDependencies: {
+-     config: [__filename, path.join(__dirname, "package.json")],
+-     ts: [path.join(__dirname, "tsconfig.json")]
+-   }
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     buildDependencies: [
++       __filename,
++       path.join(__dirname, "package.json"),
++       path.join(__dirname, "tsconfig.json")
++     ]
+    },
+  },
+};
+```
+
+3. Migrate `cache.version` and `cache.name`
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   name: `${config.name}-${config.mode}-${otherFlags}`,
+-   version: appVersion
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
+    },
+  },
+};
+```
+
+4. Migrate `snapshot`
+
+```diff title="rspack.config.js"
+module.exports = {
+- snapshot: {
+-   immutablePaths: [path.join(__dirname, "constant")],
+-   managedPaths: [path.join(__dirname, "node_modules")],
+-   unmanagedPaths: []
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     snapshot: {
++       immutablePaths: [path.join(__dirname, "constant")],
++       managedPaths: [path.join(__dirname, "node_modules")],
++       unmanagedPaths: []
++     }
+    },
+  },
+};
+```
+
+5. Migrate `cache.cacheDirectory`
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   cacheDirectory: path.join(__dirname, "node_modules/.cache/test")
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     storage: {
++       type: "filesystem",
++       directory: path.join(__dirname, "node_modules/.cache/test")
++     }
+    },
+  },
+};
+```
+
+Sample migration code:
+
+```javascript
+function transform(webpackConfig, rspackConfig) {
+  rspackConfig.experiments = rspackConfig.experiments || {};
+  if (webpackConfig.cache === undefined) {
+    webpackConfig.cache = webpackConfig.mode === 'development';
+  }
+  // 1. if using disable cache, just set `experiments.cache` = false
+  if (!webpackConfig.cache) {
+    rspackConfig.experiments.cache = false;
+    return;
+  }
+  // 2. if using memory cache, just set `experiments.cache` = true
+  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
+    rspackConfig.experiments.cache = true;
+    return;
+  }
+  // 3. using persistent cache, set `experiments.cache` = { type: "persistent" }
+  rspackConfig.experiments.cache = { type: 'persistent' };
+  // 4. building `experiments.cache` from webpack config
+  rspackConfig.experiments.cache.buildDependencies = Object.values(
+    webpackConfig.cache.buildDependencies || {},
+  ).flat();
+  rspackConfig.experiments.cache.version = [
+    webpackConfig.cache.name,
+    webpackConfig.cache.version,
+  ].join();
+  rspackConfig.experiments.cache.snapshot = {
+    immutablePaths: webpackConfig.snapshot?.immutablePaths,
+    managedPaths: webpackConfig.snapshot?.managedPaths,
+    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
+  };
+  rspackConfig.experiments.cache.storage = {
+    type: 'filesystem',
+    directory: webpackConfig.cache?.cacheDirectory,
+  };
+}
+```
diff --git a/website/docs/zh/config/experiments.mdx b/website/docs/zh/config/experiments.mdx
@@ -365,11 +365,15 @@ type ExperimentCacheOptions =
     };
 ```
 
-控制实验性的缓存行为，此配置依赖全局开启缓存，需配置 [全局cache](/config/cache) 为 `true` 才有效。
+控制实验性的缓存行为，此配置依赖全局开启缓存，需配置 [config.cache](/config/cache) 为 `true` 才有效。
+
+:::info title="Note"
+production 模式下 `config.cache` 默认值为 `false`，这会导致此配置项失效，建议直接配置 `config.cache` 为 `true`。
+:::
 
 ### 禁用缓存
 
-可以配置 `experiment.cache` 为 `false` 来禁用缓存，此时与配置 [全局cache](/config/cache) 为 `false` 没有差别。
+可以配置 `experiment.cache` 为 `false` 来禁用缓存，这与配置 [config.cache](/config/cache) 为 `false` 没有差别。
 
 ```js title="rspack.config.js"
 module.exports = {
@@ -499,3 +503,150 @@ module.exports = {
   },
 };
 ```
+
+:::tip
+Rspack 会在 `storage.directory` 目录下基于 [config.name](/config/other-options#name)，[config.mode](/config/mode#mode)，[buildDependencies](#cachebuilddependencies)中的文件内容 和 [version](#cacheversion) 生成缓存文件夹。
+
+Rspack 会在启动时自动清理掉过长时间（7 天）没有访问的缓存文件夹。
+:::
+
+### 从 webpack config 迁移
+
+Rspack cache 配置与 webpack cache 配置的用法存在差异， 你可以参考以下步骤对 webpack cache 配置进行迁移。
+
+1. 根据 webpack 缓存类型，设置 Rspack 缓存类型，持久化缓存继续后续步骤，其他类型缓存到这一步即可。
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   type: 'filesystem',
+- },
++ cache: true,
++ experiments: {
++   cache: {
++     type: 'persistent',
++   },
++ },
+};
+```
+
+2. 迁移 `cache.buildDependencies`
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   buildDependencies: {
+-     config: [__filename, path.join(__dirname, "package.json")],
+-     ts: [path.join(__dirname, "tsconfig.json")]
+-   }
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     buildDependencies: [
++       __filename,
++       path.join(__dirname, "package.json"),
++       path.join(__dirname, "tsconfig.json")
++     ]
+    },
+  },
+};
+```
+
+3. 迁移 `cache.version` & `cache.name`
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   name: `${config.name}-${config.mode}-${otherFlags}`,
+-   version: appVersion
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
+    },
+  },
+};
+```
+
+4. 迁移 `snapshot`
+
+```diff title="rspack.config.js"
+module.exports = {
+- snapshot: {
+-   immutablePaths: [path.join(__dirname, "constant")],
+-   managedPaths: [path.join(__dirname, "node_modules")],
+-   unmanagedPaths: []
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     snapshot: {
++       immutablePaths: [path.join(__dirname, "constant")],
++       managedPaths: [path.join(__dirname, "node_modules")],
++       unmanagedPaths: []
++     }
+    },
+  },
+};
+```
+
+5. 迁移 `cache.cacheDirectory`
+
+```diff title="rspack.config.js"
+module.exports = {
+- cache: {
+-   cacheDirectory: path.join(__dirname, "node_modules/.cache/test")
+- },
+  experiments: {
+    cache: {
+      type: "persistent",
++     storage: {
++       type: "filesystem",
++       directory: path.join(__dirname, "node_modules/.cache/test")
++     }
+    },
+  },
+};
+```
+
+示例代码:
+
+```javascript
+function transform(webpackConfig, rspackConfig) {
+  rspackConfig.experiments = rspackConfig.experiments || {};
+  if (webpackConfig.cache === undefined) {
+    webpackConfig.cache = webpackConfig.mode === 'development';
+  }
+  // 1. 如果使用禁用缓存，则直接配置 `experiments.cache` 为 `false`
+  if (webpackConfig.cache === false) {
+    rspackConfig.experiments.cache = false;
+    return;
+  }
+  // 2. 如果使用内存缓存，则直接配置 `experiments.cache` 为 `true`
+  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
+    rspackConfig.experiments.cache = true;
+    return;
+  }
+  // 3. 持久化缓存 配置 `experiments.cache` 为 `{ type: "persistent" }`
+  rspackConfig.experiments.cache = { type: 'persistent' };
+  // 4. 从 webpack 配置中构建 `experiments.cache` 其他配置
+  rspackConfig.experiments.cache.buildDependencies = Object.values(
+    webpackConfig.cache.buildDependencies || {},
+  ).flat();
+  rspackConfig.experiments.cache.version = [
+    webpackConfig.cache.name,
+    webpackConfig.cache.version,
+  ].join();
+  rspackConfig.experiments.cache.snapshot = {
+    immutablePaths: webpackConfig.snapshot?.immutablePaths,
+    managedPaths: webpackConfig.snapshot?.managedPaths,
+    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
+  };
+  rspackConfig.experiments.cache.storage = {
+    type: 'filesystem',
+    directory: webpackConfig.cache?.cacheDirectory,
+  };
+}
+```