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 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) => 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' | '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) => 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" | "preserve" | undefined
Decides 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) => 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: [
    {
      
LibConfig.bundle?: boolean | undefined
Whether to bundle the library.
@defaultValuetrue@seehttps://rslib.rs/config/lib/bundle
bundle: false,
      
LibConfig.format?: Format | undefined
Output format for the generated JavaScript files.
@defaultValue'esm'@seehttps://rslib.rs/config/lib/format
format: 'esm',
      
LibConfig.output?: RslibOutputConfig | undefined
Options for build outputs.
@inheritdoc
output: {
        
OutputConfig.filename?: FilenameConfig | undefined
Sets the filename of output files.
filename: {
          
js?: Filename | undefined
The name of the JavaScript files.
@default
-  dev: '[name].js'


    

  • prod: '[name].[contenthash:8].js'
    • 

js: '[name].jsx',
        },
      },
    },
  ],
  
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" | "preserve" | undefined
Decides 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) => 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'
@default"react"
importSource: '@emotion/react',
      },
    }),
  ],
});

SVGR

Read Import SVGR for more details.

Further reading