Skip to content

Commit f6210c1

Browse files
jerrykingxyzjerrykingxyz
authored
docs: add persistent cache migration (#8978)
* docs: add persistent cache migration * fix: comment * fix: comment
1 parent fa3e453 commit f6210c1

File tree

2 files changed

+306
-4
lines changed

2 files changed

+306
-4
lines changed

‎website/docs/en/config/experiments.mdx‎

Lines changed: 153 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -366,11 +366,15 @@ type ExperimentCacheOptions =
366366
};
367367
```
368368

369-
Control experimental caching behavior. This will only work if [global cache](/config/cache) is set to `true`.
369+
Control experimental caching behavior. This will only work if [config.cache](/config/cache) is set to `true`.
370+
371+
:::info title="Note"
372+
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`.
373+
:::
370374

371375
### Disable cache
372376

373-
Configuring `experiment.cache` to `false` to disable cache, which is no different from configuring the [global cache](/config/cache) to `false`.
377+
Configuring `experiment.cache` to `false` to disable cache, which is no different from configuring the [config.cache](/config/cache) to `false`.
374378

375379
```js title="rspack.config.js"
376380
module.exports = {
@@ -500,3 +504,150 @@ module.exports = {
500504
},
501505
};
502506
```
507+
508+
:::tip
509+
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).
510+
511+
Rspack will automatically clean up cache folders that have not been accessed for a long time (7 days) at startup.
512+
:::
513+
514+
### Migrating from webpack config
515+
516+
The Rspack cache configuration is different from the webpack cache configuration. You can refer to the following steps to migrate the webpack cache configuration.
517+
518+
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.
519+
520+
```diff title="rspack.config.js"
521+
module.exports = {
522+
- cache: {
523+
- type: 'filesystem',
524+
- },
525+
+ cache: true,
526+
+ experiments: {
527+
+ cache: {
528+
+ type: 'persistent',
529+
+ },
530+
+ },
531+
};
532+
```
533+
534+
2. Migrate `cache.buildDependencies`
535+
536+
```diff title="rspack.config.js"
537+
module.exports = {
538+
- cache: {
539+
- buildDependencies: {
540+
- config: [__filename, path.join(__dirname, "package.json")],
541+
- ts: [path.join(__dirname, "tsconfig.json")]
542+
- }
543+
- },
544+
experiments: {
545+
cache: {
546+
type: "persistent",
547+
+ buildDependencies: [
548+
+ __filename,
549+
+ path.join(__dirname, "package.json"),
550+
+ path.join(__dirname, "tsconfig.json")
551+
+ ]
552+
},
553+
},
554+
};
555+
```
556+
557+
3. Migrate `cache.version` and `cache.name`
558+
559+
```diff title="rspack.config.js"
560+
module.exports = {
561+
- cache: {
562+
- name: `${config.name}-${config.mode}-${otherFlags}`,
563+
- version: appVersion
564+
- },
565+
experiments: {
566+
cache: {
567+
type: "persistent",
568+
+ version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
569+
},
570+
},
571+
};
572+
```
573+
574+
4. Migrate `snapshot`
575+
576+
```diff title="rspack.config.js"
577+
module.exports = {
578+
- snapshot: {
579+
- immutablePaths: [path.join(__dirname, "constant")],
580+
- managedPaths: [path.join(__dirname, "node_modules")],
581+
- unmanagedPaths: []
582+
- },
583+
experiments: {
584+
cache: {
585+
type: "persistent",
586+
+ snapshot: {
587+
+ immutablePaths: [path.join(__dirname, "constant")],
588+
+ managedPaths: [path.join(__dirname, "node_modules")],
589+
+ unmanagedPaths: []
590+
+ }
591+
},
592+
},
593+
};
594+
```
595+
596+
5. Migrate `cache.cacheDirectory`
597+
598+
```diff title="rspack.config.js"
599+
module.exports = {
600+
- cache: {
601+
- cacheDirectory: path.join(__dirname, "node_modules/.cache/test")
602+
- },
603+
experiments: {
604+
cache: {
605+
type: "persistent",
606+
+ storage: {
607+
+ type: "filesystem",
608+
+ directory: path.join(__dirname, "node_modules/.cache/test")
609+
+ }
610+
},
611+
},
612+
};
613+
```
614+
615+
Sample migration code:
616+
617+
```javascript
618+
function transform(webpackConfig, rspackConfig) {
619+
rspackConfig.experiments = rspackConfig.experiments || {};
620+
if (webpackConfig.cache === undefined) {
621+
webpackConfig.cache = webpackConfig.mode === 'development';
622+
}
623+
// 1. if using disable cache, just set `experiments.cache` = false
624+
if (!webpackConfig.cache) {
625+
rspackConfig.experiments.cache = false;
626+
return;
627+
}
628+
// 2. if using memory cache, just set `experiments.cache` = true
629+
if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
630+
rspackConfig.experiments.cache = true;
631+
return;
632+
}
633+
// 3. using persistent cache, set `experiments.cache` = { type: "persistent" }
634+
rspackConfig.experiments.cache = { type: 'persistent' };
635+
// 4. building `experiments.cache` from webpack config
636+
rspackConfig.experiments.cache.buildDependencies = Object.values(
637+
webpackConfig.cache.buildDependencies || {},
638+
).flat();
639+
rspackConfig.experiments.cache.version = [
640+
webpackConfig.cache.name,
641+
webpackConfig.cache.version,
642+
].join();
643+
rspackConfig.experiments.cache.snapshot = {
644+
immutablePaths: webpackConfig.snapshot?.immutablePaths,
645+
managedPaths: webpackConfig.snapshot?.managedPaths,
646+
unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
647+
};
648+
rspackConfig.experiments.cache.storage = {
649+
type: 'filesystem',
650+
directory: webpackConfig.cache?.cacheDirectory,
651+
};
652+
}
653+
```

‎website/docs/zh/config/experiments.mdx‎

Lines changed: 153 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -365,11 +365,15 @@ type ExperimentCacheOptions =
365365
};
366366
```
367367

368-
控制实验性的缓存行为，此配置依赖全局开启缓存，需配置 [全局cache](/config/cache) 为 `true` 才有效。
368+
控制实验性的缓存行为，此配置依赖全局开启缓存，需配置 [config.cache](/config/cache) 为 `true` 才有效。
369+
370+
:::info title="Note"
371+
production 模式下 `config.cache` 默认值为 `false`，这会导致此配置项失效，建议直接配置 `config.cache` 为 `true`。
372+
:::
369373

370374
### 禁用缓存
371375

372-
可以配置 `experiment.cache` 为 `false` 来禁用缓存，此时与配置 [全局cache](/config/cache) 为 `false` 没有差别。
376+
可以配置 `experiment.cache` 为 `false` 来禁用缓存，这与配置 [config.cache](/config/cache) 为 `false` 没有差别。
373377

374378
```js title="rspack.config.js"
375379
module.exports = {
@@ -499,3 +503,150 @@ module.exports = {
499503
},
500504
};
501505
```
506+
507+
:::tip
508+
Rspack 会在 `storage.directory` 目录下基于 [config.name](/config/other-options#name)，[config.mode](/config/mode#mode)，[buildDependencies](#cachebuilddependencies)中的文件内容 和 [version](#cacheversion) 生成缓存文件夹。
509+
510+
Rspack 会在启动时自动清理掉过长时间（7 天）没有访问的缓存文件夹。
511+
:::
512+
513+
### 从 webpack config 迁移
514+
515+
Rspack cache 配置与 webpack cache 配置的用法存在差异， 你可以参考以下步骤对 webpack cache 配置进行迁移。
516+
517+
1. 根据 webpack 缓存类型，设置 Rspack 缓存类型，持久化缓存继续后续步骤，其他类型缓存到这一步即可。
518+
519+
```diff title="rspack.config.js"
520+
module.exports = {
521+
- cache: {
522+
- type: 'filesystem',
523+
- },
524+
+ cache: true,
525+
+ experiments: {
526+
+ cache: {
527+
+ type: 'persistent',
528+
+ },
529+
+ },
530+
};
531+
```
532+
533+
2. 迁移 `cache.buildDependencies`
534+
535+
```diff title="rspack.config.js"
536+
module.exports = {
537+
- cache: {
538+
- buildDependencies: {
539+
- config: [__filename, path.join(__dirname, "package.json")],
540+
- ts: [path.join(__dirname, "tsconfig.json")]
541+
- }
542+
- },
543+
experiments: {
544+
cache: {
545+
type: "persistent",
546+
+ buildDependencies: [
547+
+ __filename,
548+
+ path.join(__dirname, "package.json"),
549+
+ path.join(__dirname, "tsconfig.json")
550+
+ ]
551+
},
552+
},
553+
};
554+
```
555+
556+
3. 迁移 `cache.version` & `cache.name`
557+
558+
```diff title="rspack.config.js"
559+
module.exports = {
560+
- cache: {
561+
- name: `${config.name}-${config.mode}-${otherFlags}`,
562+
- version: appVersion
563+
- },
564+
experiments: {
565+
cache: {
566+
type: "persistent",
567+
+ version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
568+
},
569+
},
570+
};
571+
```
572+
573+
4. 迁移 `snapshot`
574+
575+
```diff title="rspack.config.js"
576+
module.exports = {
577+
- snapshot: {
578+
- immutablePaths: [path.join(__dirname, "constant")],
579+
- managedPaths: [path.join(__dirname, "node_modules")],
580+
- unmanagedPaths: []
581+
- },
582+
experiments: {
583+
cache: {
584+
type: "persistent",
585+
+ snapshot: {
586+
+ immutablePaths: [path.join(__dirname, "constant")],
587+
+ managedPaths: [path.join(__dirname, "node_modules")],
588+
+ unmanagedPaths: []
589+
+ }
590+
},
591+
},
592+
};
593+
```
594+
595+
5. 迁移 `cache.cacheDirectory`
596+
597+
```diff title="rspack.config.js"
598+
module.exports = {
599+
- cache: {
600+
- cacheDirectory: path.join(__dirname, "node_modules/.cache/test")
601+
- },
602+
experiments: {
603+
cache: {
604+
type: "persistent",
605+
+ storage: {
606+
+ type: "filesystem",
607+
+ directory: path.join(__dirname, "node_modules/.cache/test")
608+
+ }
609+
},
610+
},
611+
};
612+
```
613+
614+
示例代码:
615+
616+
```javascript
617+
function transform(webpackConfig, rspackConfig) {
618+
rspackConfig.experiments = rspackConfig.experiments || {};
619+
if (webpackConfig.cache === undefined) {
620+
webpackConfig.cache = webpackConfig.mode === 'development';
621+
}
622+
// 1. 如果使用禁用缓存，则直接配置 `experiments.cache` 为 `false`
623+
if (webpackConfig.cache === false) {
624+
rspackConfig.experiments.cache = false;
625+
return;
626+
}
627+
// 2. 如果使用内存缓存，则直接配置 `experiments.cache` 为 `true`
628+
if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
629+
rspackConfig.experiments.cache = true;
630+
return;
631+
}
632+
// 3. 持久化缓存 配置 `experiments.cache` 为 `{ type: "persistent" }`
633+
rspackConfig.experiments.cache = { type: 'persistent' };
634+
// 4. 从 webpack 配置中构建 `experiments.cache` 其他配置
635+
rspackConfig.experiments.cache.buildDependencies = Object.values(
636+
webpackConfig.cache.buildDependencies || {},
637+
).flat();
638+
rspackConfig.experiments.cache.version = [
639+
webpackConfig.cache.name,
640+
webpackConfig.cache.version,
641+
].join();
642+
rspackConfig.experiments.cache.snapshot = {
643+
immutablePaths: webpackConfig.snapshot?.immutablePaths,
644+
managedPaths: webpackConfig.snapshot?.managedPaths,
645+
unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
646+
};
647+
rspackConfig.experiments.cache.storage = {
648+
type: 'filesystem',
649+
directory: webpackConfig.cache?.cacheDirectory,
650+
};
651+
}
652+
```

0 commit comments

Comments
 (0)