React

在这篇文档中，你可以了解到如何基于 Rsbuild 来构建一个 React 应用。

创建 React 项目

你可以使用 create-rsbuild 来创建一个 Rsbuild + React 的项目，调用以下命令：

npm

yarn

pnpm

bun

  1. npm create rsbuild@latest

然后在 Select framework 时选择 React 即可。

在已有项目中使用 React

为了能够编译 React，你需要注册 Rsbuild 的 React 插件，插件会自动添加 React 构建所需的配置。

例如，在 rsbuild.config.ts 中注册：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  2. import { pluginReact } from '@rsbuild/plugin-react';
  4. export default defineConfig({
  5.   plugins: [pluginReact()],
  6. });

TIP

对于使用 Create React App 的项目，可以参考 CRA 迁移指南。

使用 SVGR

Rsbuild 支持调用 SVGR，将 SVG 图片转换为一个 React 组件使用。

如果你需要使用 SVGR，需要注册 Rsbuild 的 SVGR 插件。

React Fast Refresh

Rsbuild 使用 React 官方的 Fast Refresh 能力来进行组件热更新。

注意 React Refresh 要求组件按照规范的方式编写，否则热更新可能无效，你可以使用 eslint-plugin-react-refresh 进行校验。

比如，如果 React 组件的热更新无法生效，或者是热更新后 React 组件的 state 丢失，这通常是因为你的 React 组件使用了匿名函数。在 React Fast Refresh 的官方实践中，要求组件不能为匿名函数，否则热更新后无法保留 React 组件的 state。

以下是一些错误用法的例子：

  1. // 错误写法 1
  2. export default function () {
  3.   return <div>Hello World</div>;
  4. }
  6. // 错误写法 2
  7. export default () => <div>Hello World</div>;

正确用法是给每个组件函数声明一个名称：

  1. // 正确写法 1
  2. export default function MyComponent() {
  3.   return <div>Hello World</div>;
  4. }
  6. // 正确写法 2
  7. const MyComponent = () => <div>Hello World</div>;
  9. export default MyComponent;

React Compiler

React Compiler 是 React 19 引入的一个实验性编译器，它可以自动优化你的 React 代码。

在开始使用 React Compiler 之前，建议阅读 React Compiler 文档，以了解 React Compiler 的功能、当前状态和使用方法。

如何使用

在 Rsbuild 中使用 React Compiler 的步骤如下：

  1. 升级 react 和 react-dom 版本到 19。
  2. 目前 React Compiler 仅提供了 Babel 插件，你需要安装 @rsbuild/plugin-babel 和 babel-plugin-react-compiler。
  3. 在你的 Rsbuild 配置文件中注册 Babel 插件：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  2. import { pluginBabel } from '@rsbuild/plugin-babel';
  3. import { pluginReact } from '@rsbuild/plugin-react';
  5. export default defineConfig({
  6.   plugins: [
  7.     pluginReact(),
  8.     pluginBabel({
  9.       include: /\.(?:jsx|tsx)$/,
  10.       babelLoaderOptions(opts) {
  11.         opts.plugins?.unshift('babel-plugin-react-compiler');
  12.       },
  13.     }),
  14.   ],
  15. });

你也可以参考 示例项目。

配置

通过以下方式来传入 React Compiler 的配置：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  2. import { pluginBabel } from '@rsbuild/plugin-babel';
  3. import { pluginReact } from '@rsbuild/plugin-react';
  5. const ReactCompilerConfig = {
  6.   /* ... */
  7. };
  9. export default defineConfig({
  10.   plugins: [
  11.     pluginReact(),
  12.     pluginBabel({
  13.       include: /\.(?:jsx|tsx)$/,
  14.       babelLoaderOptions(opts) {
  15.         opts.plugins?.unshift([
  16.           'babel-plugin-react-compiler',
  17.           ReactCompilerConfig,
  18.         ]);
  19.       },
  20.     }),
  21.   ],
  22. });

Router

TanStack Router

TanStack Router 是一个类型安全的 React 路由，内置数据获取、缓存和一流的 search-param API。

TanStack Router 提供了 @tanstack/router-plugin 来与 Rsbuild 集成，该插件支持基于文件的路由，详见：

CSS-in-JS

使用 styled-components

Rsbuild 支持编译 styled-components，优化调试体验，并对 styled-components 添加服务器端渲染支持。

如果你需要使用 styled-components, 我们推荐使用 @rsbuild/plugin-styled-components。

你可以参考这个示例：styled-components。

使用 Emotion

Rsbuild 支持编译 Emotion，你可以添加以下配置来使用：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  2. import { pluginReact } from '@rsbuild/plugin-react';
  4. export default defineConfig({
  5.   plugins: [
  6.     pluginReact({
  7.       swcReactOptions: {
  8.         importSource: '@emotion/react',
  9.       },
  10.     }),
  11.   ],
  12.   tools: {
  13.     swc: {
  14.       jsc: {
  15.         experimental: {
  16.           plugins: [['@swc/plugin-emotion', {}]],
  17.         },
  18.       },
  19.     },
  20.   },
  21. });

你可以参考这个示例：emotion。

使用 styled-jsx

你可以通过 @swc/plugin-styled-jsx 来使用 styled-jsx：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  2. import { pluginReact } from '@rsbuild/plugin-react';
  4. export default defineConfig({
  5.   plugins: [pluginReact()],
  6.   tools: {
  7.     swc: {
  8.       jsc: {
  9.         experimental: {
  10.           plugins: [['@swc/plugin-styled-jsx', {}]],
  11.         },
  12.       },
  13.     },
  14.   },
  15. });

请注意，你需要选择和当前 @swc/core 版本匹配的 SWC 插件，才能使 SWC 正常执行，详见 tools.swc。

你可以参考这个示例：styled-jsx。

使用 vanilla-extract

Rsbuild 支持使用 @vanilla-extract/webpack-plugin 插件，你可以添加以下配置来使用 vanilla-extract：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  2. import { pluginReact } from '@rsbuild/plugin-react';
  3. import { VanillaExtractPlugin } from '@vanilla-extract/webpack-plugin';
  5. export default defineConfig({
  6.   plugins: [
  7.     pluginReact({
  8.       reactRefreshOptions: {
  9.         exclude: [/\.css\.ts$/],
  10.       },
  11.     }),
  12.   ],
  13.   tools: {
  14.     rspack: {
  15.       plugins: [new VanillaExtractPlugin()],
  16.     },
  17.   },
  18. });

你可以参考这个示例：vanilla-extract。

使用 StyleX

你可以通过 unplugin-stylex 来使用 StyleX:

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  2. import { pluginReact } from '@rsbuild/plugin-react';
  3. import stylexPlugin from 'unplugin-stylex/rspack';
  5. export default defineConfig({
  6.   plugins: [pluginReact()],
  7.   tools: {
  8.     rspack: {
  9.       plugins: [stylexPlugin()],
  10.     },
  11.   },
  12. });

你可以参考这个示例：stylex。