简体中文

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:8].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',
      },
    }),
  ],
});

SVGR

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

#React

#创建 React 项目

#在现有 Rslib 项目中使用

#JSX transform

#JSX import source

#SVGR

#进一步了解

React

创建 React 项目

在现有 Rslib 项目中使用

JSX transform

JSX import source

SVGR

进一步了解