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 add @rsbuild/plugin-react -D

Register Plugin#

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

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.

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:

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

{
  "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,
});