Create React App#

本章节介绍如何将 Create React App（简称 CRA）项目迁移到 Rsbuild。

安装依赖#

首先你需要把 CRA 的 npm 依赖替换为 Rsbuild 的依赖。

移除 CRA 的依赖：

npm remove react-scripts

安装 Rsbuild 的依赖：

npm add @rsbuild/core @rsbuild/plugin-react -D

更新 npm scripts#

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

{
  "scripts": {
-   "start": "react-scripts start",
-   "build": "react-scripts build",
-   "eject": "react-scripts eject"
+   "start": "rsbuild dev",
+   "build": "rsbuild build",
+   "preview": "rsbuild preview"
  }
}

创建配置文件#

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

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

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

这样就完成了从 CRA 到 Rsbuild 的基本迁移，此时你可以执行 npm run start 命令来尝试启动开发服务器。

使用 SVGR#

如果你使用了 CRA 的 "SVG 转 React 组件" 功能（即 SVGR），那么还需要安装 Rsbuild 的 SVGR 插件。

比如使用了以下用法：

import { ReactComponent as Logo } from './logo.svg';

const App = () => (
  <div>
    <Logo />
  </div>
);

请参考 SVGR 插件 文档了解如何在 Rsbuild 中使用 SVGR。

配置迁移#

以下是 CRA 配置对应的 Rsbuild 配置：

说明：

• 上述表格尚未覆盖到 CRA 的所有配置，欢迎补充。

编译 node_modules#

CRA 默认会使用 Babel 编译 node_modules 中的依赖，但 Rsbuild 则不会，这是为了避免二次编译带来的性能损耗和潜在的编译错误。

如果你需要处理 node_modules 中依赖引起的语法兼容性问题，可以使用 source.include 配置项来编译 node_modules。

环境变量#

CRA 默认会将 REACT_APP_ 开头的环境变量注入到 client 代码中，而 Rsbuild 默认会注入 PUBLIC_ 开头的环境变量（参考 public 变量）。

为了兼容 CRA 的行为，你可以手动调用 Rsbuild 提供的 loadEnv 方法来读取 REACT_APP_ 开头的环境变量，并通过 source.define 配置项注入到 client 代码中。

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

const { publicVars } = loadEnv({ prefixes: ['REACT_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});

内容补充#

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

Rsbuild 的文档位于 rsbuild/packages/document 目录。