React Plugin

The React plugin provides support for React, integrating features such as JSX compilation and React Refresh.

Quick Start

Install Plugin

You can install the plugin using the following command:

npm
yarn
pnpm
bun
npm add @rsbuild/plugin-react -D

Register Plugin

You can register the plugin in the rsbuild.config.ts file:

rsbuild.config.ts
import { pluginReact } from '@rsbuild/plugin-react';

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

After registering the plugin, you can directly develop React.

Options

swcReactOptions

Configure the behavior of SWC to transform React code, the same as SWC's jsc.transform.react option.

  • Type:
interface SwcReactOptions {
  pragma?: string;
  pragmaFrag?: string;
  throwIfNamespace?: boolean;
  development?: boolean;
  useBuiltins?: boolean;
  refresh?: boolean;
  runtime?: 'automatic' | 'classic';
  importSource?: string;
}
  • Default:
const isDev = process.env.NODE_ENV === 'development';
const defaultOptions = {
  development: isDev,
  refresh: isDev,
  runtime: 'automatic',
};

swcReactOptions.runtime

  • Type: 'automatic' | 'classic'
  • Default: 'automatic'

By default, Rsbuild uses the new JSX runtime introduced in React 17, which is runtime: 'automatic'.

If your current React version is lower than 16.14.0, you can set runtime to 'classic':

pluginReact({
  swcReactOptions: {
    runtime: 'classic',
  },
});

React 16.14.0 can use the new JSX runtime.

When using the classic JSX runtime, you need to manually import React in your code:

import React from 'react';

function App() {
  return <h1>Hello World</h1>;
}

swcReactOptions.importSource

  • Type: string
  • Default: 'react'

When runtime is 'automatic', you can specify the import path of the JSX runtime through importSource.

For example, when using Emotion, you can set importSource to '@emotion/react':

pluginReact({
  swcReactOptions: {
    importSource: '@emotion/react',
  },
});

splitChunks

When chunkSplit.strategy set to split-by-experience, Rsbuild will automatically split react and router related packages into separate chunks by default:

  • lib-react.js: includes react, react-dom, and react's sub-dependencies (scheduler).
  • lib-router.js: includes react-router, react-router-dom, and react-router's sub-dependencies (history, @remix-run/router).

This option is used to control this behavior and determine whether the react and router related packages need to be split into separate chunks.

  • Type:
type SplitReactChunkOptions = {
  react?: boolean;
  router?: boolean;
};
  • Default:
const defaultOptions = {
  react: true,
  router: true,
};
  • Example:
pluginReact({
  splitChunks: {
    react: false,
    router: false,
  },
});

enableProfiler

  • Type: boolean
  • Default: false

When set to true, enables the React Profiler for performance analysis in production builds. Use the React DevTools to examine profiling results and identify potential performance optimizations. Profiling adds a slight overhead, so it's disabled by default in production mode.

rsbuild.config.ts
pluginReact({
  // Only enable the profiler when REACT_PROFILER is true,
  // as the option will increase the build time and adds some small additional overhead.
  enableProfiler: process.env.REACT_PROFILER === 'true',
});

Set REACT_PROFILER=true when running build script:

package.json
{
  "scripts": {
    "build:profiler": "REACT_PROFILER=true rsbuild build"
  }
}

Since the Windows system does not support the above usage, you can also use cross-env to set environment variables. This ensures compatibility across different systems:

package.json
{
  "scripts": {
    "build:profiler": "cross-env REACT_PROFILER=true rsbuild build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}

See the React docs for details about profiling using the React DevTools.

reactRefreshOptions

  • Type:
type ReactRefreshOptions = {
  include?: string | RegExp | (string | RegExp)[] | null;
  exclude?: string | RegExp | (string | RegExp)[] | null;
  library?: string;
  forceEnable?: boolean;
};
  • Default:
const defaultOptions = {
  include: [/\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts)$/],
  exclude: [/[\\/]node_modules[\\/]/],
};

Set the options for @rspack/plugin-react-refresh. The passed value will be shallowly merged with the default value.

  • Example:
pluginReact({
  reactRefreshOptions: {
    exclude: [/some-module-to-exclude/, /[\\/]node_modules[\\/]/],
  },
});

fastRefresh

  • Type: boolean
  • Default: true

Whether to enable React Fast Refresh in development mode.

If you need to disable Fast Refresh, you can set it to false:

pluginReact({
  fastRefresh: false,
});