close
Rslib
Guide
Config
Blog
Guide
Config
Blog

React

In this document, you will learn how to build a React component library with Rslib. You can check out React related demo projects in the 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) => RsbuildPlugin
pluginReact } 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 | undefined
Options for build outputs.
@inheritdoc
output: {
    
RslibOutputConfig.target?: RsbuildTarget | undefined
Setting the build target for Rsbuild.
@override@default'node'
target: 'web',
  },
  
EnvironmentConfig.plugins?: RsbuildPlugins | undefined
Configure Rsbuild plugins.
plugins: [
function pluginReact(options?: PluginReactOptions): RsbuildPlugin
pluginReact(/** options here */)],
});

JSX transform

  • Type: 'automatic' | 'classic'
  • 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, Rsbuild uses the new JSX transform, which is runtime: 'automatic'. It requires at least React 16.14.0 or higher. The peerDependencies should be declared as "react": ">=16.14.0".

To change the JSX transform, you can pass the swcReactOptions option to the React plugin. For example, to use the classic runtime:

rslib.config.ts
import { 
const pluginReact: (options?: PluginReactOptions) => RsbuildPlugin
pluginReact } 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 | undefined
Options for build outputs.
@inheritdoc
output: {
    
RslibOutputConfig.target?: RsbuildTarget | undefined
Setting the build target for Rsbuild.
@override@default'node'
target: 'web',
  },
  
EnvironmentConfig.plugins?: RsbuildPlugins | undefined
Configure Rsbuild plugins.
plugins: [
    
function pluginReact(options?: PluginReactOptions): RsbuildPlugin
pluginReact({
      
swcReactOptions?: ReactConfig | undefined
Configure the behavior of SWC to transform React code,
the same as SWC's jsc.transform.react.
swcReactOptions: {
        
ReactConfig.runtime?: "automatic" | "classic" | undefined
jsx runtime
runtime: 'classic',
      },
    }),
  ],
});

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) => RsbuildPlugin
pluginReact } 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 | undefined
Options for build outputs.
@inheritdoc
output: {
    
RslibOutputConfig.target?: RsbuildTarget | undefined
Setting the build target for Rsbuild.
@override@default'node'
target: 'web',
  },
  
EnvironmentConfig.plugins?: RsbuildPlugins | undefined
Configure Rsbuild plugins.
plugins: [
    
function pluginReact(options?: PluginReactOptions): RsbuildPlugin
pluginReact({
      
swcReactOptions?: ReactConfig | undefined
Configure the behavior of SWC to transform React code,
the same as SWC's jsc.transform.react.
swcReactOptions: {
        
ReactConfig.importSource?: string | undefined
Declares the module specifier to be used for importing the jsx and jsxs factory functions when using runtime 'automatic'
importSource: '@emotion/react',
      },
    }),
  ],
});

SVGR

Read Import SVGR for more details.

Further reading