React 插件
React 插件提供了对 React 的支持,插件内部集成了 JSX 编译、React Refresh 等功能。
快速开始
安装插件
你可以通过如下的命令安装插件:
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 的引入路径。
比如,在使用 Emotion 时,你可以将 importSource
设置为 '@emotion/react'
:
pluginReact({
swcReactOptions: {
importSource: '@emotion/react',
},
});
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
当设置为 true
时,在生产构建中启用 React 性能分析器以用于性能分析。需要搭配 React DevTools 来检查分析结果并识别潜在的性能优化方案。分析会增加一些额外开销,因此出于性能考虑,在生产环境中默认是禁用的。
rsbuild.config.ts
pluginReact({
// 仅在 REACT_PROFILER 为 true 时启用性能分析器
// 因为该选项会增加构建时间并产生一些额外开销
enableProfiler: process.env.REACT_PROFILER === 'true',
});
执行构建脚本时,设置 REACT_PROFILER=true
即可:
REACT_PROFILER=true npx rsbuild build
关于使用 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)$/],
};
设置 @rspack/plugin-react-refresh 的选项,传入的值会与默认值进行浅合并。
pluginReact({
reactRefreshOptions: {
exclude: [/some-module-to-exclude/],
},
});