close
指南
配置
插件
API
社区

React 插件

Source

React 插件提供了对 React 的支持，插件内部集成了 JSX 编译、React Refresh 等功能。

快速开始

安装插件

你可以通过如下的命令安装插件:

npm
yarn
pnpm
bun
npm add @rsbuild/plugin-react -D

注册插件

你可以在 rsbuild.config.ts 文件中注册插件：

rsbuild.config.ts
import { pluginReact } from '@rsbuild/plugin-react';  export default {  plugins: [pluginReact()], };

注册插件后，你可以直接进行 React 开发。

选项

swcReactOptions

用于配置 SWC 转换 React 代码的行为，等价于 SWC 的 jsc.transform.react 选项。

  • 类型：
interface SwcReactOptions {  pragma?: string;  pragmaFrag?: string;  throwIfNamespace?: boolean;  development?: boolean;  useBuiltins?: boolean;  refresh?: boolean;  runtime?: 'automatic' | 'classic';  importSource?: string; }
  • 默认值：
const isDev = process.env.NODE_ENV === 'development'; const defaultOptions = {  development: isDev,  refresh: isDev,  runtime: 'automatic', };

swcReactOptions.runtime

设置 JSX runtime 的类型。

  • 类型： 'automatic' | 'classic'
  • 默认值： 'automatic'

默认情况下，Rsbuild 使用 React 17 引入的新版本 JSX runtime，即 runtime: 'automatic'。

如果你当前的 React 版本低于 16.14.0，可以将 runtime 设置为 'classic'：

pluginReact({  swcReactOptions: {  runtime: 'classic',  }, });

React 16.14.0 可以使用新版本 JSX runtime。

在使用 classic JSX runtime 时，你需要手动在代码中引入 React：

import React from 'react';  function App() {  return <h1>Hello World</h1>; }

swcReactOptions.importSource

当 runtime 为 'automatic' 时，你可以通过 importSource 来指定 JSX runtime 的引入路径。

  • 类型： string
  • 默认值： 'react'

比如，在使用 Emotion 时，你可以将 importSource 设置为 '@emotion/react'：

pluginReact({  swcReactOptions: {  importSource: '@emotion/react',  }, });

swcReactOptions.refresh

是否启用 React Fast Refresh。

大多数情况下，你应该使用插件的 fastRefresh 选项来启用或禁用 Fast Refresh。

splitChunks

在 chunkSplit.strategy 设置为 split-by-experience 时，Rsbuild 默认会自动将 react 和 router 相关的包拆分为单独的 chunk:

  • lib-react.js：包含 react，react-dom，以及 react 的子依赖（scheduler）。
  • lib-router.js：包含 react-router，react-router-dom，以及 react-router 的子依赖（history，@remix-run/router）。

该选项用于控制这一行为，决定是否需要将 react 和 router 相关的包拆分为单独的 chunk。

  • 类型：
type SplitReactChunkOptions = {  react?: boolean;  router?: boolean; };
  • 默认值：
const defaultOptions = {  react: true,  router: true, };
  • 示例：
pluginReact({  splitChunks: {  react: false,  router: false,  }, });

enableProfiler

  • 类型： boolean
  • 默认值： false

当设置为 true 时，在生产构建中启用 React 性能分析器以用于性能分析。需要搭配 React DevTools 来检查分析结果并识别潜在的性能优化方案。分析会增加一些额外开销，因此出于性能考虑，在生产模式中默认是禁用的。

rsbuild.config.ts
pluginReact({  // 仅在 REACT_PROFILER 为 true 时启用性能分析器  // 因为该选项会增加构建时间并产生一些额外开销  enableProfiler: process.env.REACT_PROFILER === 'true', });

执行构建脚本时，设置 REACT_PROFILER=true 即可：

package.json
{  "scripts": {  "build:profiler": "REACT_PROFILER=true rsbuild build"  } }

由于 Windows 系统不支持上述用法，你也可以使用 cross-env 来设置环境变量，这可以确保在不同的操作系统中都能正常使用：

package.json
{  "scripts": {  "build:profiler": "cross-env REACT_PROFILER=true rsbuild build"  },  "devDependencies": {  "cross-env": "^7.0.0"  } }

关于使用 React DevTools 进行性能分析的详细信息，请参见 React 文档。

reactRefreshOptions

  • 类型：
type ReactRefreshOptions = {  include?: string | RegExp | (string | RegExp)[] | null;  exclude?: string | RegExp | (string | RegExp)[] | null;  library?: string;  forceEnable?: boolean; };
  • 默认值：
const defaultOptions = {  include: [/\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts)$/],  exclude: [/[\\/]node_modules[\\/]/], };

设置 @rspack/plugin-react-refresh 的选项，传入的值会与默认值进行浅合并。

  • 示例：
pluginReact({  reactRefreshOptions: {  exclude: [/some-module-to-exclude/, /[\\/]node_modules[\\/]/],  }, });

fastRefresh

  • 类型： boolean
  • 默认值： true

是否在开发模式下启用 React Fast Refresh。

当 fastRefresh 设置为 true 时，@rsbuild/plugin-react 会自动注册 @rspack/plugin-react-refresh 插件。

如果你需要禁用 Fast Refresh，可以将其设置为 false：

pluginReact({  fastRefresh: false, });