Webpack#

本章节介绍如何将使用 webpack 的项目迁移到 Rsbuild。

安装依赖#

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

• 移除 webpack 的依赖：

npm remove webpack webpack-cli webpack-dev-server

• 安装 Rsbuild 的依赖：

npm add @rsbuild/core -D

更新 npm scripts#

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

{
  "scripts": {
-   "serve": "webpack serve -c webpack.config.js",
-   "build": "webpack build -c webpack.config.js",
+   "dev": "rsbuild dev",
+   "build": "rsbuild build"
  }
}

创建配置文件#

在 package.json 的同级目录下创建 Rsbuild 的配置文件 rsbuild.config.ts，并添加以下内容：

import { defineConfig } from '@rsbuild/core';

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

配置迁移#

在一个 webpack 项目中，可能已经包含了一些复杂的 webpack.config.js 配置文件。

而迁移到 Rsbuild 后，大部分 webpack 配置已经被 Rsbuild 内置，不再需要手动配置，比如 output、resolve、module.rules 等。

对于少部分需要迁移的 webpack 配置，你可以选择以下方案：

• 使用 tools.rspack 选项（Rspack 和 webpack 的配置基本上等价）。

export default {
  tools: {
    rspack: {
      plugins: [new SomeWebpackPlugin()],
    },
  },
};

• 使用 Rsbuild 中封装的配置项，比如 css-loader 的选项可以通过 tools.cssLoader 设置。

构建入口#

webpack 使用 entry 字段来设置构建入口，在 Rsbuild 中你可以使用 source.entry 来设置。

export default {
  source: {
    entry: {
      foo: './src/pages/foo/index.ts',
      bar: './src/pages/bar/index.ts',
    },
  },
};

清理配置#

由于 Rsbuild 内置了一些常见的 loader 和 plugin，所以你可以移除以下依赖和相关的配置，这会显著提升项目的依赖安装速度。

• css-loader
• babel-loader
• style-loader
• postcss-loader
• html-webpack-plugin
• mini-css-extract-plugin
• autoprefixer
• @babel/core
• @babel/preset-env
• @babel/preset-typescript
• @babel/runtime
• ...

使用插件#

Rsbuild 提供了丰富的插件，对常见的使用场景提供开箱即用的支持，你可以参考插件列表文档来了解这些插件。

我们以 React 项目为例，来介绍如何接入 Rsbuild 插件。首先，你可以移除一些 React 相关的构建依赖，它们已经被 Rsbuild React 插件内置，比如：

• react-refresh
• @babel/preset-react
• @pmmmwh/react-refresh-webpack-plugin

然后参考 React 插件 文档，注册并使用即可：

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

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

大部分常见的 webpack loaders 和 plugins 都能在 Rsbuild 中继续使用，但我们推荐你优先使用 Rsbuild 提供的插件，这能够进一步简化你的配置。下面是它们的映射关系：

配置 Dev Server#

Rsbuild 不支持使用 Rspack 的 devServer 配置项，请参考 Rspack Dev Server 进行替换。

验证结果#

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

如果在构建过程中发现问题，请根据错误日志进行调试，或者查看 webpack 配置，检查是否有一些必须的配置未被迁移到 Rsbuild。

内容补充#

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

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