Skip to content

Commit a4e40df

Browse files
9aoysanyuan0704chenjiahan
authored
docs: improve rspack migration doc (#3720)
* docs: enhance rspack-start zh doc * docs: enhance rspack-start * fix: format * Update packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx Co-authored-by: neverland <[email protected]> * Update packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx Co-authored-by: neverland <[email protected]> * Update packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx Co-authored-by: neverland <[email protected]> * Update packages/document/builder-doc/docs/en/guide/advanced/rspack-start.mdx Co-authored-by: neverland <[email protected]> * Update packages/document/builder-doc/docs/en/guide/advanced/rspack-start.mdx Co-authored-by: neverland <[email protected]> * Update packages/document/builder-doc/docs/en/guide/advanced/rspack-start.mdx Co-authored-by: neverland <[email protected]> * Update packages/document/builder-doc/docs/en/guide/advanced/rspack-start.mdx Co-authored-by: neverland <[email protected]> --------- Co-authored-by: yangxingyuan <[email protected]> Co-authored-by: neverland <[email protected]>
1 parent 26dcf3a commit a4e40df

File tree

2 files changed

+133
-15
lines changed

2 files changed

+133
-15
lines changed

‎packages/document/builder-doc/docs/en/guide/advanced/rspack-start.mdx

Lines changed: 67 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Builder aims to eliminate the main differences between different bundlers and he
6565

6666
This article will introduce the differences between webpack and Rspack from the perspective of Builder. If you need to know more in-depth differences, please refer to the [Rspack documentation](http://rspack.dev/guide/migrate-from-webpack.html).
6767

68-
### Builder configuration differences
68+
### 1. Builder configuration differences
6969

7070
Currently, most of configuration options in Builder have been adapted for Rspack.
7171
Throughout this process, Builder's work includes but is not limited to:
@@ -112,8 +112,9 @@ Unsupported configurations and capabilities include:
112112
- [output.disableSourcemap.css](/api/config-output.html#outputdisablesourcemap)
113113
- [output.enableAssetManifest](/api/config-output.html#outputenableassetmanifest)
114114
- [output.enableCssModuleTSDeclaration](/api/config-output.html#outputenablecssmoduletsdeclaration)
115-
- [output.legalComments.inline](/api/config-output.html#outputlegalcomments)
116115
- [output.enableInlineScripts](/api/config-output.html#outputenableinlinescripts)
116+
- [output.legalComments.inline](/api/config-output.html#outputlegalcomments)
117+
- [output.polyfill.usage](/api/config-output.html#usage)
117118
- tsChecker ability
118119
- [output.disableTsChecker](/api/config-output.html#outputdisabletschecker)
119120

@@ -156,30 +157,44 @@ Unsupported configurations and capabilities include:
156157
In addition to the above configurations, some of the supported configurations may have differences in their capabilities. For specific differences in configurations, please refer to the corresponding API for each configuration.
157158
:::
158159

159-
### Migrating from webpackChain to bundlerChain
160+
### 2. Migrating from webpackChain to bundlerChain
160161

161162
Builder supports modifying Rspack config via [bundlerChain](/api/config-tools.html#toolsbundlerchain). configurations modified via bundlerChain will take effect on both webpack and Rspack builds.
162163

164+
```diff
165+
export default {
166+
tools: {
167+
- webpackChain: (chain, { env }) => {
168+
+ bundlerChain: (chain, { env }) => {
169+
if (env === 'development') {
170+
chain.devtool('cheap-module-eval-source-map');
171+
}
172+
},
173+
},
174+
};
175+
```
176+
163177
:::tip
164178
The bundlerChain only provides consistent api modification for Rspack & webpack configurations, the actual plugin / loader availability depends on the actual Rspack / webpack support.
165179
:::
166180

167-
### CHAIN_ID differences
181+
#### CHAIN_ID differences
168182

169183
Because of some implementation differences between webpack and Rspack, there are some differences in the rules configuration.
170184

171185
You can see all the rules that are supported in both Rspack & webpack via [tools.bundlerChain#CHAIN_ID](/api/config-tools.html#chain_id).
172186

173-
### Modify the Rspack Configuration Object
187+
### 3. Migrating from tools.webpack to tools.rspack
174188

175189
BundlerChain only supports modifying the Rspack & webpack intersection config, more Rspack-exclusive features need to be modified via [tools.rspack](/api/config-tools.html#toolsrspack).
176190

177191
Before modify the Rspack configuration object, you may should know [the config diff between Rspack and Webapck](https://www.rspack.dev/guide/config-diff.html).
178192

179-
```ts
193+
```diff
180194
export default {
181195
tools: {
182-
rspack: (config, { env }) => {
196+
- webppack: (config, { env }) => {
197+
+ rspack: (config, { env }) => {
183198
if (env === 'development') {
184199
config.devtool = 'cheap-module-eval-source-map';
185200
}
@@ -190,3 +205,48 @@ export default {
190205
```
191206

192207
More information about Rspack, please refer to the [Rspack website](https://www.rspack.dev/).
208+
209+
### 4. Babel Configuration Migration
210+
211+
By default, Rspack uses SWC for transpilation and compression. Therefore, when using Rspack for building, babel-loader is not loaded by default.
212+
213+
For most common Babel plugins, you can find corresponding alternatives in Rspack, and there are also corresponding compatible configuration options in Builder.
214+
215+
| Babel Plugin | Rspack Configuration | Builder Configuration |
216+
| ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
217+
| @babel/preset-env | [builtins.presetEnv](https://www.rspack.dev/config/builtins.html#builtinspresetenv) | [Browserslist](/guide/advanced/browserslist.html)、<br />[Browser Compatibility](/guide/advanced/browser-compatibility.html) |
218+
| @babel/preset-react | [builtins.react](https://www.rspack.dev/config/builtins.html#builtinsreact) | [Hot Module Replacement](/guide/advanced/hmr.html) |
219+
| @emotion/babel-plugin | [builtins.emotion](https://www.rspack.dev/config/builtins.html#builtinsemotion) | Not supported |
220+
| babel-plugin-import | [builtins.pluginImport](https://www.rspack.dev/config/builtins.html#builtinspluginimport) | [source.transformImport](/api/config-source.html#sourcetransformimport) |
221+
| babel-plugin-lodash | Not supported | Not supported |
222+
| babel-plugin-styled-components | Not supported | Not supported |
223+
| @babel/plugin-react-transform-remove-prop-types | Not supported | Not supported |
224+
225+
:::Tip
226+
When using Rspack for building, you can still configure Babel plugins through [tools.babel](/api/config-tools.html#toolsbabel), but this will result in additional compilation overhead, which may slow down the Rspack build to some extent.
227+
:::
228+
229+
### 5. SWC Configuration Support
230+
231+
Rspack has built-in support for some swc configurations, such as builtins.react, which can be referred to in [Builtins](https://www.rspack.dev/config/builtins.html).
232+
233+
Adding swc plugins and more custom configurations is not currently supported in Rspack. Relevant requirements can be tracked through the corresponding [issue](https://github.com/web-infra-dev/rspack/issues/3067).
234+
235+
### 6. Webpack Plugin Migration
236+
237+
Currently, only a limited number of webpack plugins are compatible with Rspack.
238+
239+
If you are using the following plugins (or indirect dependencies) in your project, you will need to temporarily remove them or use alternative solutions, otherwise you won't be able to switch to the Rspack build:
240+
241+
- webpack-retry-chunk-load-plugin：use [output.assetsRetry](/api/config-output.html#outputassetsretry) instead.
242+
- webpack.ProviderPlugin：use [builtins.provide](https://www.rspack.dev/config/builtins.html#builtinsprovide) instead.
243+
- webpack.DefinePlugin：use [builtins.define](https://www.rspack.dev/config/builtins.html#builtinsdefine) instead.
244+
- copy-webpack-plugin：use [builtins.copy](https://www.rspack.dev/config/builtins.html#builtinscopy) instead.
245+
- banner-plugin：use [builtins.banner](https://www.rspack.dev/config/builtins.html#builtinsbanner) instead.
246+
- webpack.IgnorePlugin
247+
- webpack.ContextReplacementPlugin
248+
- ...
249+
250+
Detailed plugin support can be found at: [Plugin compatibility](https://www.rspack.dev/guide/plugin-compat.html).
251+
252+
The plugins not listed can be judged according to [Rspack Plugin API](https://www.rspack.dev/api/plugin-api.html).

‎packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx

Lines changed: 66 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Builder 旨在消除不同打包工具之间的主要差异，帮助用户以较
6565

6666
本文将从 Builder 的角度介绍 webpack 和 Rspack 之间的区别。如果需要了解更深层次的差异，请参考 [Rspack 文档](http://rspack.dev/zh/guide/migrate-from-webpack.html)。
6767

68-
### Builder 配置差异
68+
### 1. 了解 Builder 配置差异
6969

7070
目前，Builder 内大部分的配置项已经适配了 Rspack。Builder 所做的工作包括不限于：
7171

@@ -111,8 +111,9 @@ Builder 旨在消除不同打包工具之间的主要差异，帮助用户以较
111111
- [output.disableSourcemap.css](/api/config-output.html#outputdisablesourcemap)
112112
- [output.enableAssetManifest](/api/config-output.html#outputenableassetmanifest)
113113
- [output.enableCssModuleTSDeclaration](/api/config-output.html#outputenablecssmoduletsdeclaration)
114-
- [output.legalComments.inline](/api/config-output.html#outputlegalcomments)
115114
- [output.enableInlineScripts](/api/config-output.html#outputenableinlinescripts)
115+
- [output.legalComments.inline](/api/config-output.html#outputlegalcomments)
116+
- [output.polyfill.usage](/api/config-output.html#usage)
116117
- tsChecker 能力
117118
- [output.disableTsChecker](/api/config-output.html#outputdisabletschecker)
118119

@@ -155,30 +156,44 @@ Builder 旨在消除不同打包工具之间的主要差异，帮助用户以较
155156
除上述配置外，一些已支持的配置可能存在能力差异，请参考各配置 API 获取具体差异信息。
156157
:::
157158

158-
### 从 webpackChain 迁移到 bundlerChain
159+
### 2. 从 tools.webpackChain 迁移至 tools.bundlerChain
159160

160161
Builder 支持通过 [bundlerChain](/api/config-tools.html#toolsbundlerchain) 来修改 Rspack config。通过 bundlerChain 修改的配置，在 webpack 和 Rspack 构建时均可生效。
161162

163+
```diff
164+
export default {
165+
tools: {
166+
- webpackChain: (chain, { env }) => {
167+
+ bundlerChain: (chain, { env }) => {
168+
if (env === 'development') {
169+
chain.devtool('cheap-module-eval-source-map');
170+
}
171+
},
172+
},
173+
};
174+
```
175+
162176
:::tip
163177
bundlerChain 只为 Rspack & webpack 配置提供一致的 api 修改方式，实际 plugin / loader 是否可用，需要看 Rspack / webpack 实际支持情况。
164178
:::
165179

166-
### CHAIN_ID 差异
180+
#### CHAIN_ID 差异
167181

168-
因为 webpack 和 rspack 的一些实现差异，所以在规则配置上会有些不同。
182+
因为 webpack 和 Rspack 的一些实现差异，所以在规则配置上会有些不同。
169183

170184
可通过 [tools.bundlerChain#CHAIN_ID](/api/config-tools.html#chain_id) 查看所有在 Rspack & webpack 中都支持的规则。
171185

172-
### 修改 Rspack 配置
186+
### 3. 从 tools.webpack 迁移至 tools.rspack
173187

174188
BundlerChain 只支持修改 Rspack & webpack 交集部分，更多 Rspack 独有功能，需要通过 [tools.rspack](/api/config-tools.html#toolsrspack) 修改。
175189

176190
在修改 Rspack 配置之前，你可能需要了解 [Rspack 和 Webpack 的配置兼容性](https://www.rspack.dev/zh/guide/config-diff.html)。
177191

178-
```ts
192+
```diff
179193
export default {
180194
tools: {
181-
rspack: (config, { env }) => {
195+
- webppack: (config, { env }) => {
196+
+ rspack: (config, { env }) => {
182197
if (env === 'development') {
183198
config.devtool = 'cheap-module-eval-source-map';
184199
}
@@ -189,3 +204,46 @@ export default {
189204
```
190205

191206
关于 Rspack 的详细配置信息，请参考 [Rspack 官网](https://rspack.dev/)。
207+
208+
### 4. Babel 配置迁移
209+
210+
Rspack 默认会使用 SWC 进行转译和压缩，因此，在启用 Rspack 构建时，babel-loader 默认不会被启用。
211+
212+
对于大部分常见的 Babel 插件，你可以在 Rspack 中找到对应的替代品，同时 Builder 也提供了一些相应的配置项。
213+
214+
| Babel 插件 | Rspack 配置项 | Builder 配置项 |
215+
| ----------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
216+
| @babel/preset-env | [builtins.presetEnv](https://www.rspack.dev/zh/config/builtins.html#builtinspresetenv) | [设置浏览器范围](/guide/advanced/browserslist.html)、<br />[浏览器兼容性](/guide/advanced/browser-compatibility.html) |
217+
| @babel/preset-react | [builtins.react](https://www.rspack.dev/zh/config/builtins.html#builtinsreact) | [模块热替换](/guide/advanced/hmr.html) |
218+
| @emotion/babel-plugin | [builtins.emotion](https://www.rspack.dev/zh/config/builtins.html#builtinsemotion) | 暂无 |
219+
| babel-plugin-import | [builtins.pluginImport](https://www.rspack.dev/zh/config/builtins.html#builtinspluginimport) | [source.transformImport](/api/config-source.html#sourcetransformimport) |
220+
| babel-plugin-lodash | 暂无 | 暂无 |
221+
| babel-plugin-styled-components | 暂无 | 暂无 |
222+
| @babel/plugin-react-transform-remove-prop-types | 暂无 | 暂无 |
223+
224+
:::tip
225+
在使用 Rspack 构建时，仍然**支持通过 [tools.babel](/api/config-tools.html#toolsbabel) 配置 babel 插件**，但会产生额外的编译开销，在一定程度上拖慢 Rspack 构建速度。
226+
:::
227+
228+
### 5. SWC 配置支持
229+
230+
Rspack 中已内置了一部分的 swc 配置支持，如 builtins.react 等，可参考 [Builtins](https://www.rspack.dev/zh/config/builtins.html)。
231+
232+
暂不支持在 Rspack 中添加 swc 插件和更多自定义配置，相关需求可追踪对应 [issue 进度](https://github.com/web-infra-dev/rspack/issues/3067)。
233+
234+
### 6. Webpack Plugin 插件迁移
235+
236+
目前 Rspack 中兼容的 webpack 插件有限，当你的项目中有用到以下插件（或间接依赖）时，需要暂时将该插件移除或使用替代方案，否则不支持切换至 Rspack 构建：
237+
238+
- webpack-retry-chunk-load-plugin：使用 [output.assetsRetry](/api/config-output.html#outputassetsretry) 代替。
239+
- webpack.ProviderPlugin：使用 [builtins.provide](https://www.rspack.dev/zh/config/builtins.html#builtinsprovide) 代替。
240+
- webpack.DefinePlugin：使用 [builtins.define](https://www.rspack.dev/zh/config/builtins.html#builtinsdefine) 代替。
241+
- copy-webpack-plugin：使用 [builtins.copy](https://www.rspack.dev/zh/config/builtins.html#builtinscopy) 代替。
242+
- banner-plugin：使用 [builtins.banner](https://www.rspack.dev/zh/config/builtins.html#builtinsbanner) 代替。
243+
- webpack.IgnorePlugin
244+
- webpack.ContextReplacementPlugin
245+
- ...
246+
247+
具体插件支持情况可参考：[Plugin 兼容情况](https://www.rspack.dev/zh/guide/plugin-compat.html)。
248+
249+
未列出的插件可根据 [Rspack Plugin API 支持情况](https://www.rspack.dev/zh/api/plugin-api.html) 自行判断。

0 commit comments

Comments
 (0)