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

# React

This document explains how to use Rsbuild to build a React application.

## Create a React application

Create a React application with Rsbuild using [create-rsbuild](/guide/start/quick-start.md#create-an-rsbuild-application). Run this command:


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

```sh [yarn]
yarn create rsbuild
```

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

```sh [bun]
bun create rsbuild@latest
```

Then select `React` when prompted to "Select framework".

## Full-stack frameworks

The following full-stack React frameworks are built on Rsbuild and reuse Rsbuild's plugin ecosystem.

### TanStack Start

[TanStack Start](https://tanstack.com/start/latest) is a full-stack React framework powered by TanStack Router. It provides full-document SSR, streaming, Server Functions, client/server builds, and more.

- [Documentation](https://tanstack.com/start/latest)
- [Basic example](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/tanstack-start)
- [RSC example](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/tanstack-start-rsc)

You can initialize the TanStack Start example project with:

```bash
npx giget gh:rstackjs/rstack-examples/rsbuild/tanstack-start tanstack-start
cd tanstack-start
pnpm i
```

To migrate a TanStack Start project from Vite, see [TanStack Start migration](/guide/migration/tanstack-start.md).

### Modern.js

[Modern.js](https://github.com/web-infra-dev/modern.js) is a progressive web framework built on Rsbuild that provides out-of-the-box full-stack development capabilities for React applications.

## Use React in an existing project

To compile React's JSX syntax, register the Rsbuild [React plugin](/plugins/list/plugin-react.md). The plugin automatically adds the necessary configuration for building React applications.

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

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

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

:::tip
For projects using Create React App, you can refer to the [CRA Migration Guide](/guide/migration/cra.md).
:::

## Use SVGR

Rsbuild supports converting SVG to React components via [SVGR](https://react-svgr.com/).

To use SVGR, register the [SVGR plugin](/plugins/list/plugin-svgr.md).

## React Fast Refresh

Rsbuild uses React's official [Fast Refresh](https://npmjs.com/package/react-refresh) capability to perform component hot updates.

React Refresh requires components to follow certain standards, or HMR may not work. Use [eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh) to validate your code.

If React component hot updates don't work, or component state is lost after updates, your React component is likely using an anonymous function. React Fast Refresh requires named functions to preserve component state after hot updates.

Here are some examples of wrong usage:

```tsx
// bad
export default function () {
  return <div>Hello World</div>;
}

// bad
export default () => <div>Hello World</div>;
```

The correct usage is to declare a name for each component function:

```tsx
// good
export default function MyComponent() {
  return <div>Hello World</div>;
}

// good
const MyComponent = () => <div>Hello World</div>;

export default MyComponent;
```

## 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.

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

Rsbuild supports two ways to enable React Compiler:

- Recommended: enable the Rust-based React Compiler through [@rsbuild/plugin-react](/plugins/list/plugin-react.md#reactcompiler). This provides a simpler setup and better build performance.
- Optional: use [React Compiler with @rsbuild/plugin-babel](/plugins/list/plugin-babel.md#use-react-compiler) if you are maintaining an existing Babel-based setup, using an older version of Rsbuild, or need Babel-plugin-based customization.

### How to use

If you are using Rsbuild 2.1.0+, you can enable the Rust-based React Compiler directly through `@rsbuild/plugin-react`:

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

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

For React 17 and 18 projects, install [react-compiler-runtime](https://npmjs.com/package/react-compiler-runtime) and specify the `target`:

```ts title="rsbuild.config.ts"
pluginReact({
  reactCompiler: {
    target: '18', // '17' | '18' | '19'
  },
});
```

For more details, see [@rsbuild/plugin-react - reactCompiler](/plugins/list/plugin-react.md#reactcompiler).

## Router

### TanStack Router

[TanStack Router](https://tanstack.com/router/) is a fully type-safe React router with built-in data fetching, stale-while revalidate caching and first-class search-param APIs.

TanStack Router provides `@tanstack/router-plugin` to integrate with Rsbuild, which provides support for file-based routing. See:

- [Installation guide](https://tanstack.com/router/latest/docs/framework/react/installation/with-rspack)
- [Example project](https://github.com/TanStack/router/tree/main/examples/react/quickstart-rspack-file-based)

### React Router

[React Router](https://reactrouter.com/) is a user‑obsessed, standards‑focused, multi‑strategy router for React.

- To use React Router as a library, you can just follow the official documentation and no configuration is required.
- To use React Router as a framework, the community is working on an experimental Rsbuild plugin, see [rsbuild-plugin-react-router](https://github.com/rstackjs/rsbuild-plugin-react-router).

## CSS-in-JS

See [CSS-in-JS](/guide/styling/css-in-js.md) for how to use CSS-in-JS in Rsbuild.

## Customize JSX

Rsbuild uses SWC to compile JSX. You can customize the functions used by the compiled JSX code:

- If the JSX runtime is `automatic`, use [importSource](/plugins/list/plugin-react.md#swcreactoptionsimportsource) to customize the import path of the JSX runtime, for example, import from Preact or Emotion.
- If the JSX runtime is `classic`, use `pragma` and `pragmaFrag` to specify the JSX function and Fragment component.

> `@rsbuild/plugin-react` uses `automatic` as the default JSX runtime, see [swcReactOptions.runtime](/plugins/list/plugin-react.md#swcreactoptionsruntime).

### Via configuration

Configure through the `@rsbuild/plugin-react`'s [swcReactOptions](/plugins/list/plugin-react.md#swcreactoptions).

- If `runtime` is `automatic`:

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

export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'automatic',
        importSource: '@emotion/react',
      },
    }),
  ],
});
```

- If `runtime` is `classic`:

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

export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'classic',
        pragma: 'h',
        pragmaFrag: 'Fragment',
      },
    }),
  ],
});
```

### Via comments

You can also customize JSX behavior by adding specific comments at the top of individual JSX or TSX files, which will take precedence over the configuration.

- If the JSX runtime is `automatic`:

```tsx title="App.tsx"
/** @jsxImportSource custom-jsx-library */

const App = () => {
  return <div>Hello World</div>;
};
```

- If the JSX runtime is `classic`:

```tsx title="App.tsx"
/** @jsx Preact.h */
/** @jsxFrag Preact.Fragment */

const App = () => {
  return <div>Hello World</div>;
};
```

## React Server Components

To use React Server Components (RSC) in a React application, you can use the [rsbuild-plugin-rsc](https://github.com/rstackjs/rsbuild-plugin-rsc) plugin.

Built on top of [Environments API](/guide/advanced/environments.md#environment-api), this plugin encapsulates the core capabilities required for RSC scenarios, allowing you to organize server and client components within the same application and simplify the integration and configuration process.

## Performance profiling

### React Scan

React Scan can automatically detect performance issues in your React app.

See [React Scan - Rsbuild Guide](https://github.com/aidenybai/react-scan/blob/main/docs/installation/rsbuild.md) to learn how to use React Scan with Rsbuild.