English

React

In this document, you will learn how to build a React component library with Rslib. You can check out React related example projects in Examples.

Create React project

You can use create-rslib to create a project with Rslib + React. Just execute the following command:

npm

yarn

pnpm

bun

npm create rslib@latest

Then select React when prompted to "Select template".

Use Rslib in an existing project

To develop a React library, you need to set the target to "web" in rslib.config.ts. This is crucial because Rslib sets the target to "node" by default, which differs from the default target of Rsbuild.

To compile React (JSX and TSX), you need to register the Rsbuild React Plugin. The plugin will automatically add the necessary configuration for React builds.

For example, register in 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

Type: 'automatic' | 'classic' | 'preserve'
Default: 'automatic'

React introduced a new JSX transform in version 17. This new transform removes the need to import React when using JSX.

By default, Rslib uses the new JSX transform, which is runtime: 'automatic'. It requires at least React 16.14.0 or higher and the peerDependencies should be specified as "react": ">=16.14.0".

To change the JSX transform, you can set the swcReactOptions option in @rsbuild/plugin-react.

For example, to use the 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',
      },
    }),
  ],
});

When you need to keep native JSX in the build output, you can set the runtime to 'preserve' to leave JSX syntax unchanged without transforming it, which is useful for subsequent processing by other bundlers.

WARNING

When using runtime: 'preserve', you must set bundle: false to enable bundleless mode to keep files unbundled.

To emit .jsx files, you can configure the JS filename template through output.filename option:

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

Type: string
Default: 'react'

When runtime is set to 'automatic', you can specify the import path of the JSX transform through importSource.

For example, when using Emotion, you can set importSource to '@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

Read Import SVGR for more details.

React

In this document, you will learn how to build a React component library with Rslib. You can check out React related example projects in Examples.

Create React project

You can use create-rslib to create a project with Rslib + React. Just execute the following command:

npm

yarn

pnpm

bun

npm create rslib@latest

Then select React when prompted to "Select template".

Use Rslib in an existing project

To compile React (JSX and TSX), you need to register the Rsbuild React Plugin. The plugin will automatically add the necessary configuration for React builds.

For example, register in 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

Type: 'automatic' | 'classic' | 'preserve'
Default: 'automatic'

React introduced a new JSX transform in version 17. This new transform removes the need to import React when using JSX.

By default, Rslib uses the new JSX transform, which is runtime: 'automatic'. It requires at least React 16.14.0 or higher and the peerDependencies should be specified as "react": ">=16.14.0".

To change the JSX transform, you can set the swcReactOptions option in @rsbuild/plugin-react.

For example, to use the 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',
      },
    }),
  ],
});

WARNING

When using runtime: 'preserve', you must set bundle: false to enable bundleless mode to keep files unbundled.

To emit .jsx files, you can configure the JS filename template through output.filename option:

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

Type: string
Default: 'react'

When runtime is set to 'automatic', you can specify the import path of the JSX transform through importSource.

For example, when using Emotion, you can set importSource to '@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

Read Import SVGR for more details.

React

Create React project

Use Rslib in an existing project

JSX transform

JSX import source

SVGR

Further reading

React

Create React project

Use Rslib in an existing project

JSX transform

JSX import source

SVGR

Further reading

#React

#Create React project

#Use Rslib in an existing project

#JSX transform

#JSX import source

#SVGR

#Further reading

#React

#Create React project

#Use Rslib in an existing project

#JSX transform

#JSX import source

#SVGR

#Further reading

React

Create React project

Use Rslib in an existing project

JSX transform

JSX import source

SVGR

Further reading

React

Create React project

Use Rslib in an existing project

JSX transform

JSX import source

SVGR

Further reading