升级至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
函数的参数修改为一个对象,你可以指定去读取自定义的配置文件。具体的函数签名请参考源码。