Webpack

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

安装依赖

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

  • 移除 webpack 的依赖:
npm
yarn
pnpm
bun
npm remove webpack webpack-cli webpack-dev-server
  • 安装 Rsbuild 的依赖:
npm
yarn
pnpm
bun
npm add @rsbuild/core -D

更新 npm scripts

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

package.json
{
  "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,并添加以下内容:

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 的配置基本上等价)。
rsbuild.config.ts
export default {
  tools: {
    rspack: {
      plugins: [new SomeWebpackPlugin()],
    },
  },
};
  • 使用 Rsbuild 中封装的配置项,比如 css-loader 的选项可以通过 tools.cssLoader 设置。

构建入口

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

rsbuild.config.ts
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
  • ...
TIP

以上仅列出了一些可以被移除的常见依赖。在一个真实的 webpack 项目中,可能还存在很多其他依赖,请酌情处理。

使用插件

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 提供的插件,这能够进一步简化你的配置。下面是它们的映射关系:

webpack Rsbuild
@babel/preset-react React 插件
vue-loader Vue 插件Vue 2 插件
svelte-loader Svelte 插件
babel-preset-solid Solid 插件
babel-loader Babel 插件
sass-loader Sass 插件
less-loader Less 插件
stylus-loader Stylus 插件
mdx-loader MDX 插件
pug-loader Pug 插件
yaml-loader Yaml 插件
toml-loader Toml 插件
@svgr/webpack SVGR 插件
fork-ts-checker-webpack-plugin Type Check 插件
node-polyfill-webpack-plugin Node Polyfill 插件
@vue/babel-plugin-jsx Vue JSX 插件
@vue/babel-preset-jsx Vue 2 JSX 插件
eslint-webpack-plugin ESLint 插件
lightningcss-loader Lightning CSS 插件
babel-plugin-styled-components Styled Components 插件

配置 Dev Server

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

验证结果

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

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

内容补充

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

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