> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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](https://github.com/rstackjs/rstack-examples/tree/main/rslib).

## Create React project

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


```sh [npm]
npm create rslib@latest
```

```sh [yarn]
yarn create rslib
```

```sh [pnpm]
pnpm create rslib@latest
```

```sh [bun]
bun 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](/config/rsbuild/output.md#outputtarget) 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](https://rsbuild.rs/plugins/list/plugin-react). The plugin will automatically add the necessary configuration for React builds.

For example, register in `rslib.config.ts`:

```ts title="rslib.config.ts" twoslash
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react'; // [!code highlight]

export default defineConfig({
  lib: [
    // ...
  ],
  // [!code highlight:4]
  output: {
    target: 'web',
  },
  plugins: [pluginReact(/** options here */)],
});
```

## JSX transform

- **Type:** `'automatic' | 'classic' | 'preserve'`
- **Default:** `'automatic'`

React introduced a [new JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) 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](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime) option in `@rsbuild/plugin-react`.

For example, to use the classic runtime:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ...
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      // [!code highlight:3]
      swcReactOptions: {
        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](/guide/basic/output-structure.md#bundle--bundleless) to keep files unbundled.

:::

To emit `.jsx` files, you can configure the JS filename template through [output.filename](/config/rsbuild/output.md#outputfilename) option:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      bundle: false,
      format: 'esm',
      // [!code highlight:5]
      output: {
        filename: {
          js: '[name].jsx',
        },
      },
    },
  ],
  plugins: [
    pluginReact({
      swcReactOptions: {
        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](https://emotion.sh/), you can set `importSource` to `'@emotion/react'`:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ...
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      // [!code highlight:3]
      swcReactOptions: {
        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](https://react.dev/learn/react-compiler) to understand its functionality, current state, and usage.

### How to use

Steps to use React Compiler in Rslib:

1. Upgrade `react` and `react-dom` to v19. If you can't upgrade, install the [react-compiler-runtime](https://npmjs.com/package/react-compiler-runtime) package to run the compiled code on earlier versions.
2. Enable React Compiler through the `reactCompiler` option of `@rsbuild/plugin-react`:

```ts title="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](https://github.com/rstackjs/rstack-examples/tree/main/rslib/react-compiler).

### Configuration

Pass a config object to customize the React Compiler behavior. For all available options, refer to the [`reactCompiler`](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) option of `@rsbuild/plugin-react`.

```ts title="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](https://npmjs.com/package/react-compiler-runtime) and specify the `target`:

```ts title="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](https://react.dev/reference/react-compiler/configuration).

### 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](https://rsbuild.rs/plugins/list/plugin-babel) and [babel-plugin-react-compiler](https://npmjs.com/package/babel-plugin-react-compiler), then register the Babel plugin in your Rslib config file:

```ts title="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](/guide/advanced/svgr-files.md) for more details.

## Further reading

- [Rsbuild React Plugin](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime)
- [SWC Compilation - jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact)