close
  • 简体中文

      • 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
      yarn
      pnpm
      bun
      deno
      npm remove @modern-js/builder-cli @modern-js/builder-webpack-provider @modern-js/builder-rspack-provider
      • 安装 Rsbuild 的依赖：
      npm
      yarn
      pnpm
      bun
      deno
      npm add @rsbuild/core -D

      更新 npm scripts

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

      package.json
      {
  "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。
      rsbuild.config.ts
      import { defineConfig } from '@modern-js/builder-cli'; 
import { defineConfig } from '@rsbuild/core'; 

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

      替换插件

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

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

      BuilderRsbuild
      @modern-js/builder-plugin-vue@rsbuild/plugin-vue
      @modern-js/builder-plugin-vue2@rsbuild/plugin-vue2
      @modern-js/builder-plugin-stylus@rsbuild/plugin-stylus
      @modern-js/builder-plugin-node-polyfill@rsbuild/plugin-node-polyfill
      @modern-js/builder-plugin-image-compress@rsbuild/plugin-image-compress
      @modern-js/builder-plugin-swc默认生效，无须使用
      @modern-js/builder-plugin-esbuild不再支持

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

      rsbuild.config.ts
      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 插件：

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

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

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

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

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

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

      配置迁移

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

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

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

      验证结果

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

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

      内容补充

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

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