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" for details.
  • Manual configuration: You can refer to the current document to manually add configurations for React.

Configure JSX/TSX

Rspack leverages SWC transformer for JSX/TSX.

Add builtin:swc-loader loader to support jsx and tsx:

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
      {
        test: /\.tsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'typescript',
                tsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};

Refer to Builtin swc-loader for detailed configurations.

Fast Refresh

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

builtins.react.refresh

Stability: Deprecated

In the early stage of Rspack, React Fast Refresh functionality was built into @rspack/dev-server and @rspack/core to provide an out-of-the-box experience for some projects. This means that if you are using @rspack/cli or @rspack/dev-server, React Fast Refresh is automatically enabled in development mode, ready for you to use directly in your projects. This enhanced the usability of Rspack for React projects but also led to various issues.

This approach made Rspack not entirely framework-agnostic. If you were using other frameworks like Vue, you had to manually disable React Fast Refresh functionality using builtins.react.refresh to avoid injecting React Fast Refresh-related code into some Vue modules.

Recognizing this issue, we aim to gradually transition users to a more correct approach through experiments.rspackFuture.disableTransformByDefault and @rspack/plugin-react-refresh, which represents the second method mentioned.

@rspack/plugin-react-refresh

WARNING

@rspack/plugin-react-refresh depends on experiments.rspackFuture.disableTransformByDefault

First you need to install the dependencies:

npm
yarn
pnpm
bun
npm add @rspack/plugin-react-refresh react-refresh -D

Enabling React Fast Refresh functionality primarily involves two aspects: code injection and code transformation.

rspack.config.js
const ReactRefreshPlugin = require('@rspack/plugin-react-refresh');
const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  experiments: {
    rspackFuture: {
      disableTransformByDefault: true,
    },
  },
  // ...
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              transform: {
                react: {
                  development: isDev,
                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
  plugins: [isDev && new ReactRefreshPlugin()].filter(Boolean),
};

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:

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 to understand the functionality, current state, and usage of the React Compiler.

TIP

At present, React Compiler only supports Babel compilation, which may slow down the build time.

How to use

The steps to use React Compiler in Rspack:

  1. Upgrade versions of react and react-dom to 19.
  2. React Compiler currently only provides a Babel plugin, you need to install:
  1. Register babel-loader in your Rspack config file:
rspack.config.js
module.exports = {
  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' },
        ],
      },
    ],
  },
};
  1. Create a babel.config.js and configure the plugins:
babel.config.js
// babel.config.js
const ReactCompilerConfig = {
  /* ... */
};

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

Examples

You can refer to the following example projects:

Integrating SVGR

SVGR is an universal tool for transforming Scalable Vector Graphics (SVG) files into React components.

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

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

For detailed usage of SVGR, please refer to SVGR Documentation - Webpack.