ContextQMD
Back to Rspack

React

website/docs/en/guide/tech/react.mdx

2.1.19.1 KB
Original Source

import { PackageManagerTabs } from '@theme'; import { Stability } from '@components/ApiMeta.tsx';

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 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 loader to support .jsx and .tsx files:

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

Refer to builtin:swc-loader 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 to support React Fast Refresh.

<PackageManagerTabs command="add @rspack/plugin-react-refresh react-refresh -D" />

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

js
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:

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.

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 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
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
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 to control which functions are compiled.

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

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:

Register babel-loader in your Rspack config file:

js
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
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 and specify the target:

js
const ReactCompilerConfig = {
  target: '18', // '17' | '18' | '19'
};

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.

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

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

React Server Components

If you need to use React Server Components, please refer to Rspack - React Server Components.