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

# React

## How to use

Rspack provides two solutions to support React:

- **Use Rsbuild**: Rsbuild provides out-of-the-box support for React, allowing you to quickly create a React project. See [Rsbuild - React](https://rsbuild.rs/guide/framework/react) for details.
- **Manual configure Rspack**: You can refer to the current document to manually add configurations for React.

## Configure JSX/TSX

Rspack leverages SWC transformer for supporting JSX and TSX.

You can add [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader.md) loader to support `.jsx` and `.tsx` files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
          },
        },
      },
    ],
  },
};
```

Refer to [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader.md) for detailed configurations.

## Fast Refresh

There are currently two ways to enable React Fast Refresh in Rspack:

First you need to install [@rspack/plugin-react-refresh](https://www.npmjs.com/package/@rspack/plugin-react-refresh) to support React Fast Refresh.


```sh [npm]
npm add @rspack/plugin-react-refresh react-refresh -D
```

```sh [yarn]
yarn add @rspack/plugin-react-refresh react-refresh -D
```

```sh [pnpm]
pnpm add @rspack/plugin-react-refresh react-refresh -D
```

```sh [bun]
bun add @rspack/plugin-react-refresh react-refresh -D
```

```sh [deno]
deno add npm:@rspack/plugin-react-refresh npm:react-refresh -D
```

Enabling [React Fast Refresh](https://reactnative.dev/docs/fast-refresh) functionality primarily involves two aspects: code injection and code transformation.

- Code injection will inject some code from the `react-refresh` package, as well as some custom runtime code, all of which are integrated in the [@rspack/plugin-react-refresh](https://github.com/rstackjs/rspack-plugin-react-refresh) plugin and can be injected through this plugin.
- Code transformation can be added through loaders, such as [jsc.transform.react.refresh](https://swc.rs/docs/configuration/compilation#jsctransformreactrefresh) for swc-loader or the [react-refresh/babel](https://github.com/facebook/react/tree/main/packages/react-refresh) for babel-loader.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';
import { ReactRefreshRspackPlugin } from '@rspack/plugin-react-refresh';

const isDev = process.env.NODE_ENV === 'development';

export default {
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  development: isDev,
                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
  plugins: [
    isDev && new ReactRefreshRspackPlugin(),
    isDev && new rspack.HotModuleReplacementPlugin(),
  ],
};
```

Compared to the previous approach, this method decouples the React Fast Refresh code injection logic from the transformation logic. The code injection logic is handled uniformly by the @rspack/plugin-react-refresh plugin, while the code transformation is handled by loaders. This means that this plugin can be used in conjunction with `builtin:swc-loader`, `swc-loader`, or `babel-loader`:

- For usage with `builtin:swc-loader`, you can refer to the example at [examples/react-refresh](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-refresh), When using with `swc-loader`, simply replace `builtin:swc-loader` with `swc-loader`.
- For usage with `babel-loader`, you can refer to the example at [examples/react-refresh-babel-loader](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-refresh-babel-loader)

## React Compiler

React Compiler is an experimental compiler introduced in React 19 that can automatically optimize your React code.

Before you start using React Compiler, it's recommended to read the [React Compiler documentation](https://react.dev/learn/react-compiler) to understand the functionality, current state, and usage of the React Compiler.

### Using `builtin:swc-loader`

The steps to use React Compiler in Rspack:

1. Upgrade `@rspack/core` to v2.1.0 or later.
2. Upgrade versions of `react` and `react-dom` to 19. If you are unable to upgrade, you can install the extra [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) package which will allow the compiled code to run on versions prior to 19.
3. Enable React Compiler in `builtin:swc-loader` through `jsc.transform.reactCompiler`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  runtime: 'automatic',
                },
                reactCompiler: true,
              },
            },
          },
        },
      },
    ],
  },
};
```

For React 17 and 18 projects, set the compiler target:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  runtime: 'automatic',
                },
                reactCompiler: {
                  target: '18',
                },
              },
            },
          },
        },
      },
    ],
  },
};
```

The `reactCompiler` options are aligned with the React Compiler configuration. For example, you can use [`compilationMode`](https://react.dev/reference/react-compiler/compilationMode) to control which functions are compiled.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  runtime: 'automatic',
                },
                reactCompiler: {
                  compilationMode: 'annotation',
                },
              },
            },
          },
        },
      },
    ],
  },
};
```

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 available in the SWC transform yet.

To use Babel, install:

- [@babel/core](https://www.npmjs.com/package/@babel/core)
- [babel-loader](https://www.npmjs.com/package/babel-loader)
- [babel-plugin-react-compiler](https://www.npmjs.com/package/babel-plugin-react-compiler)
- [@babel/plugin-syntax-jsx](https://www.npmjs.com/package/@babel/plugin-syntax-jsx)

Register `babel-loader` in your Rspack config file:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              // SWC options for JS
            },
          },
        ],
      },
      {
        test: /\.jsx$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              // SWC options for JSX
            },
          },
          { loader: 'babel-loader' },
        ],
      },
    ],
  },
};
```

Create a `babel.config.js` and configure the plugins:

```js title="babel.config.js"
const ReactCompilerConfig = {/* ... */};

module.exports = function () {
  return {
    plugins: [
      ['babel-plugin-react-compiler', ReactCompilerConfig], // must run first!
      '@babel/plugin-syntax-jsx',
    ],
  };
};
```

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

```js title="babel.config.js"
const ReactCompilerConfig = {
  target: '18', // '17' | '18' | '19'
};
```

### Examples

You can refer to the following example projects:

- [Rspack + React Compiler](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-compiler-babel)
- [Rspack + React Compiler + TypeScript](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-compiler-babel-ts)

## Integrating SVGR

[SVGR](https://react-svgr.com/) is an universal tool for transforming [Scalable Vector Graphics (SVG)](https://en.wikipedia.org/wiki/SVG) files into React components.

The usage of SVGR with Rspack is exactly the same as with Webpack.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        issuer: /\.[jt]sx?$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};
```

For detailed usage of SVGR, please refer to [SVGR Documentation - webpack](https://react-svgr.com/docs/webpack/).

## React Server Components

If you need to use React Server Components, please refer to [Rspack - React Server Components](https://rspack.rs/guide/integrations/rsc.md).