feat(builder): add source.reactCompiler to enable React Compiler (#8763)

Author: keepview

.changeset/spicy-donkeys-attack.md

@@ -0,0 +1,7 @@
+---
+'@modern-js/builder': minor
+'@modern-js/app-tools': minor
+---
+
+feat(builder): add `source.reactCompiler` to enable React Compiler via Rspack's built-in SWC implementation
+feat(builder): 新增 `source.reactCompiler` 配置，基于 Rspack 内置 SWC 的 Rust 版 React Compiler 提供一键开启能力

examples/react-compiler/modern.config.ts

@@ -1,14 +1,9 @@
 import { appTools, defineConfig } from '@modern-js/app-tools';
-import { pluginBabel } from '@rsbuild/plugin-babel';
 
 // https://modernjs.dev/en/configure/app/usage
 export default defineConfig({
-  builderPlugins: [
-    pluginBabel({
-      babelLoaderOptions: (_config, { addPlugins }) => {
-        addPlugins(['babel-plugin-react-compiler']);
-      },
-    }),
-  ],
+  source: {
+    reactCompiler: true,
+  },
   plugins: [appTools()],
 });

examples/react-compiler/package.json

@@ -22,12 +22,10 @@
     "@biomejs/biome": "1.9.4",
     "@modern-js/app-tools": "latest",
     "@modern-js/tsconfig": "latest",
-    "@rsbuild/plugin-babel": "^1.1.2",
     "@types/jest": "~29.2.4",
     "@types/node": "^20",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "babel-plugin-react-compiler": "^1.0.0",
     "eslint-plugin-react-hooks": "^6.0.0-rc.1",
     "rimraf": "^6.0.1",
     "typescript": "~5.7.3"

packages/cli/builder/package.json

@@ -38,7 +38,7 @@
     "@rsbuild/plugin-check-syntax": "2.0.0",
     "@rsbuild/plugin-css-minimizer": "2.0.1",
     "@rsbuild/plugin-less": "1.6.4",
-    "@rsbuild/plugin-react": "2.0.1",
+    "@rsbuild/plugin-react": "2.1.0",
     "@rsbuild/plugin-rem": "1.0.6",
     "@rsbuild/plugin-sass": "1.5.3",
     "@rsbuild/plugin-source-build": "1.0.6",

packages/cli/builder/src/shared/parseCommonConfig.ts

@@ -70,7 +70,13 @@ export async function parseCommonConfig(
       ...outputConfig
     } = {},
     html: { outputStructure, appIcon, ...htmlConfig } = {},
-    source: { alias, globalVars, transformImport, ...sourceConfig } = {},
+    source: {
+      alias,
+      globalVars,
+      transformImport,
+      reactCompiler,
+      ...sourceConfig
+    } = {},
     dev = {},
     server = {},
     security: { checkSyntax, sri, ...securityConfig } = {},
@@ -269,7 +275,9 @@ export async function parseCommonConfig(
     );
   }
 
-  rsbuildPlugins.push(pluginReact());
+  rsbuildPlugins.push(
+    pluginReact(reactCompiler !== undefined ? { reactCompiler } : {}),
+  );
 
   if (!disableSvgr) {
     const { pluginSvgr } = await import('@rsbuild/plugin-svgr');

packages/cli/builder/src/types.ts

@@ -22,6 +22,7 @@ import type { PluginAssetsRetryOptions } from '@rsbuild/plugin-assets-retry';
 import type { PluginCheckSyntaxOptions } from '@rsbuild/plugin-check-syntax';
 import type { PluginCssMinimizerOptions } from '@rsbuild/plugin-css-minimizer';
 import type { PluginLessOptions } from '@rsbuild/plugin-less';
+import type { PluginReactOptions } from '@rsbuild/plugin-react';
 import type { PluginRemOptions } from '@rsbuild/plugin-rem';
 import type { PluginSassOptions } from '@rsbuild/plugin-sass';
 import type { PluginSourceBuildOptions } from '@rsbuild/plugin-source-build';
@@ -175,6 +176,12 @@ export type BuilderExtraConfig = {
      * Define global variables. It can replace expressions like `process.env.FOO` in your code after compile.
      */
     globalVars?: ChainedGlobalVars;
+    /**
+     * Enable or configure React Compiler, powered by the Rust-based implementation
+     * built into Rspack's `builtin:swc-loader` (`jsc.transform.reactCompiler`).
+     * @default undefined (disabled)
+     */
+    reactCompiler?: PluginReactOptions['reactCompiler'];
   };
   output?: {
     /**

packages/cli/builder/tests/reactCompiler.test.ts

@@ -0,0 +1,87 @@
+import { join } from 'path';
+import type { Rspack } from '@rsbuild/core';
+import { describe, expect, test } from '@rstest/core';
+import { createBuilder } from '../src';
+import { parseCommonConfig } from '../src/shared/parseCommonConfig';
+import type { BuilderConfig } from '../src/types';
+
+function getSwcTransformOptions(config: Rspack.Configuration) {
+  for (const rule of config.module?.rules || []) {
+    if (!rule || typeof rule !== 'object') {
+      continue;
+    }
+    const uses = Array.isArray(rule.use) ? rule.use : [rule.use];
+    for (const use of uses) {
+      if (
+        use &&
+        typeof use === 'object' &&
+        use.loader?.includes('swc-loader') &&
+        typeof use.options === 'object'
+      ) {
+        return (use.options as Rspack.SwcLoaderOptions).jsc?.transform;
+      }
+    }
+  }
+  return undefined;
+}
+
+async function getBundlerConfig(config: BuilderConfig) {
+  const rsbuild = await createBuilder({
+    bundlerType: 'rspack',
+    config,
+    cwd: join(__dirname, '..'),
+  });
+  const {
+    origin: { bundlerConfigs },
+  } = await rsbuild.inspectConfig();
+  return bundlerConfigs[0];
+}
+
+describe('source.reactCompiler', () => {
+  test('should not enable react compiler by default', async () => {
+    const transform = getSwcTransformOptions(await getBundlerConfig({}));
+
+    expect(transform).toBeDefined();
+    expect(transform).not.toHaveProperty('reactCompiler');
+  });
+
+  test('should enable react compiler when set to true', async () => {
+    const transform = getSwcTransformOptions(
+      await getBundlerConfig({
+        source: {
+          reactCompiler: true,
+        },
+      }),
+    );
+
+    expect(transform?.reactCompiler).toEqual(true);
+  });
+
+  test('should pass through react compiler options object', async () => {
+    const transform = getSwcTransformOptions(
+      await getBundlerConfig({
+        source: {
+          reactCompiler: {
+            target: '18',
+            compilationMode: 'annotation',
+          },
+        },
+      }),
+    );
+
+    expect(transform?.reactCompiler).toEqual({
+      target: '18',
+      compilationMode: 'annotation',
+    });
+  });
+
+  test('should not leak reactCompiler into rsbuild source config', async () => {
+    const { rsbuildConfig } = await parseCommonConfig({
+      source: {
+        reactCompiler: true,
+      },
+    });
+
+    expect(rsbuildConfig.source).not.toHaveProperty('reactCompiler');
+  });
+});

packages/document/docs/en/configure/app/source/react-compiler.mdx

@@ -0,0 +1,72 @@
+---
+title: reactCompiler
+---
+
+# source.reactCompiler
+
+- **Type:** `boolean | ReactCompilerOptions`
+- **Default:** `undefined` (disabled)
+
+Whether to enable [React Compiler](https://react.dev/learn/react-compiler). React Compiler is a build-time tool that optimizes re-rendering performance of React applications through automatic memoization.
+
+Modern.js implements this capability based on the Rust-based React Compiler built into Rspack's `builtin:swc-loader` (equivalent to setting SWC's `jsc.transform.reactCompiler`), reusing Rspack's built-in SWC transform chain without introducing Babel.
+
+:::tip
+This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
+:::
+
+## Example
+
+### Enable React Compiler (React 19)
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+});
+```
+
+### Using with React 18
+
+The compiled output targets React 19 by default. To use it in React 18 projects, you need to:
+
+1. Install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) as a **runtime dependency** (the compiled output references it at runtime):
+
+```bash
+npm add react-compiler-runtime
+```
+
+2. Specify the React version via `target`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
+});
+```
+
+### Customize compilation behavior
+
+When passing an object, the options are the same as Rspack's `jsc.transform.reactCompiler`. For example, use `compilationMode: 'annotation'` to only compile functions annotated with the `"use memo"` directive:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+For the complete list of options, see [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) and the [React Compiler configuration docs](https://react.dev/reference/react-compiler/configuration).

packages/document/docs/en/guides/advanced-features/page-performance/react-compiler.mdx

@@ -1,54 +1,69 @@
 # React Compiler
 
-The React Compiler is an experimental compiler introduced in React 19 that can automatically optimize your React code.
+React Compiler is a build-time compiler from the React team that reduces unnecessary re-renders through automatic memoization, without manually writing `useMemo`, `useCallback`, or `React.memo`.
 
-Before starting to use the React Compiler, it is recommended to read the [React Compiler documentation](https://zh-hans.react.dev/learn/react-compiler) to understand its features, current status, and usage.
+Before starting to use React Compiler, it is recommended to read the [React Compiler documentation](https://react.dev/learn/react-compiler) to understand its features, current status, and usage.
 
 ## How to Use
 
-### React 19
+Modern.js provides built-in support for React Compiler via the [source.reactCompiler](/configure/app/source/react-compiler) option, powered by the Rust-based React Compiler implementation in Rspack's `builtin:swc-loader`. It reuses Rspack's built-in SWC transform chain without introducing Babel (`babel-plugin-react-compiler`).
 
-If you are using React 19, Modern.js has built-in support for React Compiler, and no additional configuration is required.
+This capability is **disabled by default** and must be enabled explicitly for any React version.
 
-### React 18
+### React 19
 
-If you are using React 18, you need to configure it as follows:
+If you are using React 19, simply enable `source.reactCompiler` — no additional dependencies are required:
 
-1. Install `react-compiler-runtime` to allow the compiled code to run on versions before 19:
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
-```bash
-npm install react-compiler-runtime
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+  plugins: [appTools()],
+});
 ```
 
-2. Install `babel-plugin-react-compiler`:
+### React 18
+
+If you are using React 18, configure it as follows:
+
+1. Install `react-compiler-runtime` as a **runtime dependency** to allow the compiled code to run on versions before React 19:
 
 ```bash
-npm install babel-plugin-react-compiler
+npm add react-compiler-runtime
 ```
 
-3. Register the Babel plugin in your Modern.js configuration file:
+2. Specify the React version via `target` in the configuration:
 
 ```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
-import { pluginBabel } from '@rsbuild/plugin-babel';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginBabel({
-      babelLoaderOptions: (config, { addPlugins }) => {
-        addPlugins([
-          [
-            'babel-plugin-react-compiler',
-          {
-            target: '18', // 或 '17'，根据你使用的 React 版本
-          },
-          ],
-        ]);
-      },
-    });
-  ];
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
   plugins: [appTools()],
 });
 ```
 
+## Customize Compilation Behavior
+
+`source.reactCompiler` accepts an object to configure the compilation behavior, with the same options as Rspack's `jsc.transform.reactCompiler`. For example, use `compilationMode: 'annotation'` to only compile functions annotated with the `"use memo"` directive, enabling React Compiler incrementally:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+For the complete list of options, see [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) and the [React Compiler configuration docs](https://react.dev/reference/react-compiler/configuration).
+
 > For detailed code, you can refer to the [Modern.js & React Compiler example project](https://github.com/web-infra-dev/modern.js/tree/main/examples/react-compiler)