Skip to main content

升级至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.finalizedevServer.finalizebuild.script.finalize三个函数支持异步返回。以build.finalize为例,你可以返回WebpackConfigurationPromise<WebpackConfiguration>,reSKRipt在调用时会妥善处理你的返回值。

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

internals参数中的loaderloaders,以及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中能够引入的loadersrules对象被分别转移到了@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-webpackloaders对象和build.finalizeinternals参数暴露的postCSSpostCSSModules这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的requirerequire.resovle函数引用。
  • @reskript/config-webpack中的loadersrules导出发生了变化,请参考config-webpack导出变更
  • V4版本的@reskript/config-webpack/loaders@reskript/config-webpack/rules导出的各个函数均为异步返回。
  • postCSSpostCSSModules这2个loader配置已经改名为postcss,请参考loader命名修改
  • @reskript/settingsreadProjectSettingswatchProjectSettings函数的参数修改为一个对象,你可以指定去读取自定义的配置文件。具体的函数签名请参考源码。