升级至V4

本文摘录了reSKRipt V3 -> V4版本的所有破坏性变更，如果你正在使用3.x版本，可以参考本文进行升级。如果你在升级过程中遇到任何困难，欢迎在GitHub上提交Issue来咨询。

V4的主要变化是实现全部更新到了ESM格式，因此相关的配置文件格式需要相应升级。同时为了性能的提升，配置中的*.finalize函数和相关的辅助函数均升级成了异步函数。

自动检测

你可以先使用我们的迁移脚本对项目做一次快速地扫描：

# 保持在项目根目录下
npx @reskript/doctor migrate

按照报告的说明进行修复后，如果依然有问题，以下是各变更的详细介绍。

依赖升级

以下是V4版本的依赖相关的调整。

安装settings包

从V4开始，为了更好地协助你编写配置文件，你需要显式地安装@reskript/settings包，且版本与其它包保持相同。

在升级@reskript/*包时，你可以同时加上@reskript/settings，你的package.json的变化大致如下：

 {
     "devDependencies": {
-        "@reskript/cli": "3.0.6",
-        "@reskript/cli-build": "3.0.6",
-        "@reskript/cli-dev": "3.0.6",
-        "@reskript/cli-lint": "3.0.6",
-        "@reskript/cli-play": "3.0.6",
-        "@reskript/cli-test": "3.0.6",
-        "@reskript/config-lint": "3.0.6",
+        "@reskript/cli": "4.0.0",
+        "@reskript/cli-build": "4.0.0",
+        "@reskript/cli-dev": "4.0.0",
+        "@reskript/cli-lint": "4.0.0",
+        "@reskript/cli-play": "4.0.0",
+        "@reskript/cli-test": "4.0.0",
+        "@reskript/config-lint": "4.0.0",
+        "@reskript/settings": "4.0.0",
     }
 }

在此后，你可以在配置文件中直接使用import {configure} from '@reskript/settings'来获得配置过程的类型提示、自动完成等功能，我们会在后文中详细描述。

NodeJS版本

V4要求你的NodeJS版本为^14.18.0 || >= 16.0.0，即必须是14.18.0以上的版本，且不支持15.x。对于已经使用V3版本的用户，如果你没有使用15.x版本的NodeJS，就不需要关注这一变更。

配置变更

以下为配置文件格式、内容、类型上的变化。

项目配置文件

从V4版本开始，你的项目配置文件必须以.ts或.mjs为扩展名，我们强烈推荐使用.ts作为你的配置文件。

以.ts为例，默认的配置文件为reskript.config.ts，当然你可以使用新的--config参数来指定一个自定义的配置文件。

除扩展名外，配置文件的内容也需要相应的修改。在V4中，配置文件的内容必须为一个ESM模块，使用export default导出。我们通过@reskript/settings包提供了configure函数来帮助你快速编写配置，configure函数的使用请参考配置 - 配置文件。

通常来说，在经过修改后，你的配置文件的exports.*会变为configure的第2个参数中的具体属性，整体会有以下的变化：

+ import {configure} from '@reskript/settings';

+ export default configure(
+     'webpack',
+     {
- exports.featureMatrix = {
-     // ...
- };
+         featureMatrix: {
+             // ...
+         },
- exports.build = {
-     // ...
- };
+         build: {
+             // ...
+         }
- exports.devServer = {
-     // ...
- };
+         devServer: {
+             // ...
+         }
- exports.play = {
-     // ...
- };
+         play: {
+             // ...
+         }
+     }
+ );

此处，还请注意配置文件中的一些特殊变量和函数调用：

• __dirname和__filename在ESM下不可用，请用fileURLToPath(import.url.meta)代替__filename。
• require在ESM下不可用，请改用import。
• require.resovle在ESM下不可用，如果你能确定路径，请使用path.join计算路径。如果实在需要require.resolve，可以尝试使用resolve包。

note

resolve包在纯ESM下或许也有一些问题，如果你确实需要，可以通过issue向我们咨询。

finalize函数异步化

在V4版本中，项目配置中的build.finalize、devServer.finalize和build.script.finalize三个函数支持异步返回。以build.finalize为例，你可以返回WebpackConfiguration或Promise<WebpackConfiguration>，reSKRipt在调用时会妥善处理你的返回值。

通常来说，因为reSKRipt兼容同步和异步的返回，从V3更新到V4并不需要做出修改。但是当你使用了build.finalize的第3个参数internals时，则需要做出相应的修改。

internals参数中的loader和loaders，以及rules对象中的所有函数，均被更新为了异步函数，因此在使用它们时，你需要添加await来得到正确的返回值。

以增加SASS的处理为例，你的代码可能有如下的变化：

 build: {
     finalize: (webpackConfig, context, internals) => {
         const sassRule = {
             test: /\.sass$/,
             use: [
-                ...internals.loaders('classNames', 'style', 'cssModules', 'postcss'),
+                ...await internals.loaders('classNames', 'style', 'cssModules', 'postcss'),
                 'sass-loader',
             ],
         };
         webpackConfig.module.rules.push(sassRule);
         return webpackConfig;
     },
 }

config-webpack导出变更

在V4版本中，原本从@reskript/config-webpack中能够引入的loaders和rules对象被分别转移到了@reskript/config-webpack/loaders和@reskript/config-webpack/rules下，且更改为命名导出。

如果你在配置中有使用这2个对象，那么需要相应修改：

- import {loaders, rules} from '@reskript/config-webpack';
+ import * as loaders from '@reskript/config-webpack/loaders';
+ import * as rules from '@reskript/config-webpack/rules';

loader命名修改

从V4版本开始，原本通过@reskript/config-webpack的loaders对象和build.finalize的internals参数暴露的postCSS与postCSSModules这2个loader的命名发生了调整，它们被统一修改为postcss这一名称。

如果你原本使用这2个loader，则需要相应调整代的代码：

- loaders.postCSSModule(...);
+ loaders.postcss(...);

- internals.loader('postCSS');
+ internals.loader('postcss');

入口配置调整

原有reSKRipt支持的入口配置，即entries（或指定的入口目录）下的*.config.js，也因ESM化的影响需要做相应的修改。

从V4开始，入口配置文件必须以.ts或.mjs作为扩展名，我们强烈推荐使用.ts作为扩展。

入口配置文件的内容也需要调整为ESM格式，将原有的exports.*修改为export const，你的改动大致如下：

- exports.html = {
+ export const html = {
     // ...
 };

- exports.entry = {
+ export const entry = {
     // ...
 };

插件

API调整

如果你有编程式地调用@reskript/*包中的函数，那么你需要阅读这个章节，了解我们暴露的API的变化：

• 除了@reskript/eslint-plugin和@reskript/config-jest外，所有的包都以ESM格式发布，你无法在CommonJS模块中使用它们。仅@reskript/eslint-config/config下的内容、@reskript/config-lint/patch模块依然可以通过CommonJS的require或require.resovle函数引用。
• @reskript/config-webpack中的loaders和rules导出发生了变化，请参考config-webpack导出变更。
• V4版本的@reskript/config-webpack/loaders和@reskript/config-webpack/rules导出的各个函数均为异步返回。
• postCSS和postCSSModules这2个loader配置已经改名为postcss，请参考loader命名修改。
• @reskript/settings的readProjectSettings和watchProjectSettings函数的参数修改为一个对象，你可以指定去读取自定义的配置文件。具体的函数签名请参考源码。