#React

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

#创建 React 应用

使用 create-rsbuild 来创建一个基于 Rsbuild 的 React 应用，运行以下命令：

npm create rsbuild@latest

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

#在已有项目中使用 React

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

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

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

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

#使用 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
export default function () {
  return <div>Hello World</div>;
}

// 错误写法 2
export default () => <div>Hello World</div>;

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

// 正确写法 1
export default function MyComponent() {
  return <div>Hello World</div>;
}

// 正确写法 2
const MyComponent = () => <div>Hello World</div>;

export default MyComponent;

#React Compiler

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

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

#如何使用

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

1. 升级 react 和 react-dom 版本到 19。如果你暂时无法升级，可以在 React 17 或 18 项目中安装 react-compiler-runtime，以允许编译后的代码在 19 之前的版本上运行。
2. 目前 React Compiler 仅提供了 Babel 插件，你需要安装 @rsbuild/plugin-babel 和 babel-plugin-react-compiler。
3. 在你的 Rsbuild 配置文件中注册 Babel 插件：

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

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
      babelLoaderOptions(opts) {
        opts.plugins?.unshift('babel-plugin-react-compiler');
      },
    }),
  ],
});

你也可以参考 示例项目。

#配置

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

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

const ReactCompilerConfig = {
  /* ... */
};

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
      babelLoaderOptions(opts) {
        opts.plugins?.unshift([
          'babel-plugin-react-compiler',
          ReactCompilerConfig,
        ]);
      },
    }),
  ],
});

对于 React 17 和 18 的项目，除了安装 react-compiler-runtime，还需要指定 target：

const ReactCompilerConfig = {
  target: '18', // '17' | '18' | '19'
};

#路由

#TanStack Router

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

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

• 安装指南
• 示例项目

#React Router

React Router 是一个以用户为中心、注重标准的 React 多策略路由库。

• 如果你想将 React Router 作为库来使用，只需按照官方文档操作即可，无需额外配置。
• 如果你想将 React Router 作为框架来使用，社区正在开发一个实验性的 Rsbuild 插件，参考 rsbuild-plugin-react-router。

#CSS-in-JS

参考 CSS-in-JS 了解如何在 Rsbuild 中使用 CSS-in-JS。

#自定义 JSX

Rsbuild 使用 SWC 来编译 JSX，你可以自定义编译后的 JSX 代码所使用的函数：

• 当 JSX 的 runtime 为 automatic 时，使用 jsxImportSource 来自定义 JSX runtime 的导入路径，比如从 Preact 或 Emotion 中引入。
• 当 JSX 的 runtime 为 classic 时，使用 pragma 和 pragmaFrag 来指定 JSX 函数和 Fragment 组件。

@rsbuild/plugin-react 默认使用的 JSX runtime 为 automatic，详见 swcReactOptions.runtime。

#通过配置

通过 @rsbuild/plugin-react 的 swcReactOptions 来配置。

• 当 runtime 为 automatic 时：

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

export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'automatic',
        jsxImportSource: '@emotion/react',
      },
    }),
  ],
});

• 当 runtime 为 classic 时：

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

export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'classic',
        pragma: 'h',
        pragmaFrag: 'Fragment',
      },
    }),
  ],
});

#通过注释

你也可以通过在单个 JSX 或 TSX 文件顶部添加特定注释来自定义 JSX 行为，这些注释的优先级会高于配置项。

• 当 JSX 的 runtime 为 automatic 时：

/** @jsxImportSource custom-jsx-library */

const App = () => {
  return <div>Hello World</div>;
};

• 当 JSX 的 runtime 为 classic 时：

/** @jsx Preact.h */
/** @jsxFrag Preact.Fragment */

const App = () => {
  return <div>Hello World</div>;
};

#性能分析

#React Scan

React Scan 可以自动检测 React 应用中的性能问题。

参考 React Scan - Rsbuild Guide 了解如何在 Rsbuild 中使用 React Scan。