React

在本文档中，你将学习如何使用 Rslib 构建 React 组件库，你可在示例中查看 React 相关演示项目。

创建 React 项目

你可以使用 create-rslib 创建 Rslib + React 项目。只需执行以下命令：

npm

yarn

pnpm

bun

npm create rslib@latest

然后，当提示 "Select template" 时选择 React。

在现有 Rslib 项目中使用

开发 React 组件，需要在 rslib.config.ts 中设置 target 为 "web"。这一点至关重要，因为 Rslib 默认将 target 设置为 "node"，这与 Rsbuild 的 target 默认值不同。

要编译 React（JSX 和 TSX），你需要注册 Rsbuild React 插件。该插件将自动添加 React 构建所需的配置。

例如，在 rslib.config.ts 中注册:

rslib.config.ts

import { function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig } from '@rslib/core';
import { const pluginReact: (options?: PluginReactOptions) => RsbuildPluginpluginReact } from '@rsbuild/plugin-react'; 

export default function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig({
  RslibConfig.lib: LibConfig[]lib: [
    // ...
  ],
  RslibConfig.output?: RslibOutputConfig | undefinedOptions for build outputs.
@inheritdocoutput: {
    RslibOutputConfig.target?: RsbuildTarget | undefinedSetting the build target for Rsbuild.
@override@default'node'target: 'web',
  },
  EnvironmentConfig.plugins?: RsbuildPlugins | undefinedConfigure Rsbuild plugins.plugins: [function pluginReact(options?: PluginReactOptions): RsbuildPluginpluginReact(/** options here */)],
});

JSX transform

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

React 引入了一个新的 JSX transform 在版本 17 中。这个新的 transform 在使用 JSX 时无需导入 React。

默认情况下，Rslib 使用新的 JSX 转换，即 runtime: 'automatic'。这需要 React 16.14.0 或更高版本，且 peerDependencies 中应声明 "react": ">=16.14.0"。

要更改 JSX transform，可以在 @rsbuild/plugin-react 中设置 swcReactOptions 选项。

比如要使用 classic runtime 时：

rslib.config.ts

import { const pluginReact: (options?: PluginReactOptions) => RsbuildPluginpluginReact } from '@rsbuild/plugin-react';
import { function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig } from '@rslib/core';

export default function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig({
  RslibConfig.lib: LibConfig[]lib: [
    // ...
  ],
  RslibConfig.output?: RslibOutputConfig | undefinedOptions for build outputs.
@inheritdocoutput: {
    RslibOutputConfig.target?: RsbuildTarget | undefinedSetting the build target for Rsbuild.
@override@default'node'target: 'web',
  },
  EnvironmentConfig.plugins?: RsbuildPlugins | undefinedConfigure Rsbuild plugins.plugins: [
    function pluginReact(options?: PluginReactOptions): RsbuildPluginpluginReact({
      swcReactOptions?: ReactConfig | undefinedConfigure the behavior of SWC to transform React code,
the same as SWC's jsc.transform.react.swcReactOptions: {
        ReactConfig.runtime?: "automatic" | "classic" | "preserve" | undefinedDecides which runtime to use when transforming JSX.

"automatic" - Automatically imports the functions that JSX transpiles to.
This is the modern approach introduced in React 17+ that eliminates the need to
manually import React in every file that uses JSX.
"classic" - Uses the traditional JSX transform that relies on React.createElement
calls. Requires React to be in scope, which was the standard behavior before React 17.
"preserve" - Leaves JSX syntax unchanged without transforming it.
@default"classic"runtime: 'classic',
      },
    }),
  ],
});

当你希望在构建产物中保留原始 JSX 时，可以将 runtime 设置为 'preserve'。该模式可以保持 JSX 语法原样，不做任何转换，方便后续由其他打包工具处理。

Warning

使用 runtime: 'preserve' 时，必须设置 bundle: false 启用 bundleless 模式使文件保持非打包状态。

若要输出 .jsx 后缀的文件，可通过 output.filename 配置 JS 文件名模版：

rslib.config.ts

import { const pluginReact: (options?: PluginReactOptions) => RsbuildPluginpluginReact } from '@rsbuild/plugin-react';
import { function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig } from '@rslib/core';

export default function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig({
  RslibConfig.lib: LibConfig[]lib: [
    {
      LibConfig.bundle?: boolean | undefinedWhether to bundle the library.
@defaultValuetrue@seehttps://rslib.rs/config/lib/bundlebundle: false,
      LibConfig.format?: Format | undefinedOutput format for the generated JavaScript files.
@defaultValue'esm'@seehttps://rslib.rs/config/lib/formatformat: 'esm',
      LibConfig.output?: RslibOutputConfig | undefinedOptions for build outputs.
@inheritdocoutput: {
        OutputConfig.filename?: FilenameConfig | undefinedSets the filename of output files.filename: {
          js?: Filename | undefinedThe name of the JavaScript files.
@default-  dev: '[name].js'

prod: '[name].[contenthash:10].js'
js: '[name].jsx',
        },
      },
    },
  ],
  EnvironmentConfig.plugins?: RsbuildPlugins | undefinedConfigure Rsbuild plugins.plugins: [
    function pluginReact(options?: PluginReactOptions): RsbuildPluginpluginReact({
      swcReactOptions?: ReactConfig | undefinedConfigure the behavior of SWC to transform React code,
the same as SWC's jsc.transform.react.swcReactOptions: {
        ReactConfig.runtime?: "automatic" | "classic" | "preserve" | undefinedDecides which runtime to use when transforming JSX.

"automatic" - Automatically imports the functions that JSX transpiles to.
This is the modern approach introduced in React 17+ that eliminates the need to
manually import React in every file that uses JSX.
"classic" - Uses the traditional JSX transform that relies on React.createElement
calls. Requires React to be in scope, which was the standard behavior before React 17.
"preserve" - Leaves JSX syntax unchanged without transforming it.
@default"classic"runtime: 'preserve',
      },
    }),
  ],
});

JSX import source

类型: string
默认值: 'react'

当 runtime 的值为 'automatic'，可以通过 importSource 指定 JSX transform 的 import 路径。

例如，当使用 Emotion，你可以设置 importSource 为 '@emotion/react':

rslib.config.ts

import { const pluginReact: (options?: PluginReactOptions) => RsbuildPluginpluginReact } from '@rsbuild/plugin-react';
import { function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig } from '@rslib/core';

export default function defineConfig(config: RslibConfig): RslibConfig (+3 overloads)This function helps you to autocomplete configuration types.
It accepts a Rslib config object, or a function that returns a config.defineConfig({
  RslibConfig.lib: LibConfig[]lib: [
    // ...
  ],
  RslibConfig.output?: RslibOutputConfig | undefinedOptions for build outputs.
@inheritdocoutput: {
    RslibOutputConfig.target?: RsbuildTarget | undefinedSetting the build target for Rsbuild.
@override@default'node'target: 'web',
  },
  EnvironmentConfig.plugins?: RsbuildPlugins | undefinedConfigure Rsbuild plugins.plugins: [
    function pluginReact(options?: PluginReactOptions): RsbuildPluginpluginReact({
      swcReactOptions?: ReactConfig | undefinedConfigure the behavior of SWC to transform React code,
the same as SWC's jsc.transform.react.swcReactOptions: {
        ReactConfig.importSource?: string | undefinedDeclares the module specifier to be used for importing the jsx and jsxs factory
functions when using runtime 'automatic'
@default"react"importSource: '@emotion/react',
      },
    }),
  ],
});

React Compiler

React Compiler 是一个构建时工具，它可以自动优化你的 React 应用。它支持纯 JavaScript，并且了解 React 的规则，因此你无需重写任何代码即可使用它。

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

如何使用

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

升级 react 和 react-dom 版本到 19。如果你暂时无法升级，可以在 React 17 或 18 项目中安装 react-compiler-runtime，以允许编译后的代码在 19 之前的版本上运行。
通过 @rsbuild/plugin-react 的 reactCompiler 选项启用 React Compiler：

rslib.config.ts

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

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

该方式使用了集成在 builtin:swc-loader 中的 Rust 版本 React Compiler，比 Babel 版本快约 7-13 倍。

你也可以参考示例项目。

配置

传入配置对象以自定义 React Compiler 的行为。所有可用选项请参考 @rsbuild/plugin-react 的 reactCompiler 选项。

rslib.config.ts

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

export default defineConfig({
  plugins: [
    pluginReact({
      reactCompiler: {
        compilationMode: 'annotation',
      },
    }),
  ],
});

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

rslib.config.ts

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

export default defineConfig({
  plugins: [
    pluginReact({
      reactCompiler: {
        target: '18', // '17' | '18' | '19'
      },
    }),
  ],
});

reactCompiler 的配置选项与 React Compiler 官方配置对齐。更多选项请参考 React Compiler 配置文档。

使用 Babel

你也可以使用 React Compiler 提供的 Babel 插件。这在你需要 Babel 特有的集成或 SWC transform 中尚不可用的选项时很有用。

安装 @rsbuild/plugin-babel 和 babel-plugin-react-compiler，然后在 Rslib 配置文件中注册 Babel 插件：

rslib.config.ts

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

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginBabel({
      include: /\.[jt]sx?$/,
      exclude: [/[\\/]node_modules[\\/]/],
      babelLoaderOptions(opts) {
        opts.plugins ??= [];
        opts.plugins.unshift('babel-plugin-react-compiler');
      },
    }),
  ],
});

SVGR

阅读 SVGR 了解更多详细信息。

#React

#创建 React 项目

#在现有 Rslib 项目中使用

#JSX transform

#JSX import source

#React Compiler

#如何使用

#配置

#使用 Babel

#SVGR

#进一步了解

React

创建 React 项目

在现有 Rslib 项目中使用

JSX transform

JSX import source

React Compiler

如何使用

配置

使用 Babel

SVGR

进一步了解