#webpack

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

#安装依赖

首先，将 webpack 相关的 npm 依赖替换为 Rsbuild 的依赖。

• 移除 webpack 的依赖：

npm remove webpack webpack-cli webpack-dev-server

yarn remove webpack webpack-cli webpack-dev-server

pnpm remove webpack webpack-cli webpack-dev-server

bun remove webpack webpack-cli webpack-dev-server

deno remove npm:webpack npm:webpack-cli npm:webpack-dev-server

• 安装 Rsbuild 的依赖：

npm add @rsbuild/core -D

yarn add @rsbuild/core -D

pnpm add @rsbuild/core -D

bun add @rsbuild/core -D

deno add npm:@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",
    "build": "rsbuild build"
  }
}

#创建配置文件

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

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

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

查看 配置 Rsbuild 了解更多。

#配置迁移

在一个 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 设置。

参考 配置 Rspack 了解更多。

#构建入口

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/plugin-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 defineConfig({
  plugins: [pluginReact()],
});

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

#配置 Dev server

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

#Babel 迁移

Rsbuild 默认使用 SWC 编译代码，所以大部分常用的 Babel 插件不再需要，下面是一些常见的 Babel 插件的迁移示例。

#@babel/preset-env

@babel/preset-env 不再需要，Rsbuild 会自动根据 browserslist 配置进行代码降级。

注意 Rsbuild 默认不会注入 polyfill。参考 Polyfill 方案 了解如何注入 polyfill。

#@babel/preset-typescript

@babel/preset-typescript 不再需要，因为 Rsbuild 开启 SWC 的 TypeScript 转换。

#@babel/preset-react

@babel/preset-react 不再需要，替换为 @rsbuild/plugin-react 即可。

#@babel/plugin-transform-runtime

@babel/plugin-transform-runtime 不再需要，Rsbuild 中内置了等价的 @swc/helpers 作为 runtime helpers。

#babel-plugin-import

babel-plugin-import 插件可以替换为 Rsbuild 的 source.transformImport 配置项。

• Babel 配置：

module.exports = {
  plugins: [['import', { libraryName: 'some-library', libraryDirectory: 'es', style: true }]],
};

• Rsbuild 配置：

export default {
  source: {
    transformImport: [{ libraryName: 'some-library', libraryDirectory: 'es', style: true }],
  },
};

#验证结果

完成以上步骤后，即已完成从 webpack 到 Rsbuild 的基本迁移。运行 npm run dev 启动开发服务器。

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

#内容补充

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

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