Modern.js Builder#

本章节介绍如何将使用 Modern.js Builder (或 EdenX Builder) 的项目迁移到 Rsbuild。

主要区别#

Rsbuild 是 Modern.js Builder 的新版本，主要区别如下：

• Rsbuild 的性能更出色，在同时使用 Rspack 的情况下，Rsbuild 的启动速度和构建速度是 Builder 的 1.5 ~ 2 倍。
• Rsbuild 仅支持 Rspack 作为打包工具，不再支持 Webpack。
• Rsbuild 的 CLI 工具和 dev server 更加强大，支持更多功能。

安装依赖#

首先你需要把 Builder 相关的 npm 依赖替换为 Rsbuild 的依赖。

• 移除 Builder 的依赖：

npm remove @modern-js/builder-cli @modern-js/builder-webpack-provider @modern-js/builder-rspack-provider

• 安装 Rsbuild 的依赖：

npm add @rsbuild/core -D

更新 npm scripts#

下一步，你需要把 package.json 中的 npm scripts 更新为 Rsbuild 的 CLI 命令。

{
  "scripts": {
-   "dev": "builder dev",
-   "build": "builder build",
-   "serve": "builder serve"
+   "dev": "rsbuild dev",
+   "build": "rsbuild build",
+   "preview": "rsbuild preview"
  }
}

修改配置文件#

• 将 builder.config.ts 重命名为 rsbuild.config.ts。
• 从 @modern-js/builder-cli 中导入 defineConfig 方法，改为从 @rsbuild/core 中导入。
• 将 builderPlugins 字段改为 plugins。

- import { defineConfig } from '@modern-js/builder-cli';
+ import { defineConfig } from '@rsbuild/core';

export default defineConfig({
-  builderPlugins: [],
+  plugins: [],
});

替换插件#

Rsbuild 和 Builder 的插件系统不兼容，因此需要将 Builder 的插件替换为 Rsbuild 的插件。

下面是 Builder 插件和 Rsbuild 插件的对应关系：

以 @modern-js/builder-plugin-vue 为例，你需要先安装 @rsbuild/plugin-vue，然后在 rsbuild.config.ts 中引入插件，并添加到 plugins 字段中。

- import { builderPluginVue } from '@modern-js/builder-plugin-vue';
+ import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
-  builderPlugins: [builderPluginVue()],
+  plugins: [pluginVue()],
});

添加 React 相关插件#

Rsbuild 不与任何前端 UI 框架耦合。因此，如果你是一个 React 项目，需要手动添加 React 插件：

import { pluginReact } from '@rsbuild/plugin-react';

export default {
  plugins: [pluginReact()],
};

如果你当前项目中有使用 SVGR，还需要注册 Rsbuild 的 SVGR 插件：

import { pluginSvgr } from '@rsbuild/plugin-svgr';

export default {
  plugins: [pluginSvgr()],
};

如果你是其他框架的使用者，可参考 插件列表 选择对应的框架插件。

配置迁移#

Rsbuild 和 Builder 的绝大多数配置项是一致的，仅有少许配置项进行了调整。

你可以通过 Rsbuild 配置项 来查看 Rsbuild 的配置项。

值得注意的是，相比 Builder，Rsbuild 中一些默认值和行为存在差异：

• 浏览器范围：默认最低兼容到支持 原生 ES Modules 的浏览器，可参考 Browserslist 默认值。
• HTML 文件输出位置：默认输出到 dist 目录的根部，可参考 默认产物目录。
• Polyfill 注入方式：默认按需注入，可参考 output.polyfill。
• TypeScript 类型检查：默认不开启，需要手动注册 @rsbuild/plugin-type-check。
• 修改 DevServer 配置：通过 dev 和 server 配置项修改。

验证结果#

完成以上步骤后，你已经完成了从 Modern.js Builder 到 Rsbuild 的基本迁移，此时可以执行 npm run dev 命令来尝试启动开发服务器。

如果在构建过程中发现问题，请根据错误日志进行调试。

内容补充#

当前文档只涵盖了迁移过程的部分事项，如果你发现有合适的内容可以补充，欢迎通过 pull request 来完善文档 🤝。

Rsbuild 的文档位于 rsbuild/website 目录。