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: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

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

React Compiler

React Compiler is a build-time tool that automatically optimizes your React app. It works with plain JavaScript, and understands the Rules of React, so you don't need to rewrite any code to use it.

Before using React Compiler, we recommend reading the React Compiler documentation to understand its functionality, current state, and usage.

How to use

Steps to use React Compiler in Rslib:

Upgrade react and react-dom to v19. If you can't upgrade, install the react-compiler-runtime package to run the compiled code on earlier versions.
Enable React Compiler through the reactCompiler option of @rsbuild/plugin-react:

rslib.config.ts

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

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

This uses the Rust version of React Compiler integrated in builtin:swc-loader, which is around 7-13x faster than the Babel version.

You can also refer to the example project.

Configuration

Pass a config object to customize the React Compiler behavior. For all available options, refer to the reactCompiler option of @rsbuild/plugin-react.

rslib.config.ts

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

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

For React 17 and 18 projects, install react-compiler-runtime and specify the 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'
      },
    }),
  ],
});

The reactCompiler options are aligned with the React Compiler configuration. For more options, refer to the official React Compiler configuration documentation.

Using Babel

You can also use the Babel plugin published by React Compiler. This is useful if you need Babel-specific integration or options that are not yet available in the SWC transform.

Install @rsbuild/plugin-babel and babel-plugin-react-compiler, then register the Babel plugin in your Rslib config file:

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

Read SVGR for more details.

#React

#Create React project

#Use Rslib in an existing project

#JSX transform

#JSX import source

#React Compiler

#How to use

#Configuration

#Using Babel

#SVGR

#Further reading

React

Create React project

Use Rslib in an existing project

JSX transform

JSX import source

React Compiler

How to use

Configuration

Using Babel

SVGR

Further reading