@modern-js/main-doc 3.6.0 → 3.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/docs/en/configure/app/source/react-compiler.mdx +72 -0
  2. package/docs/en/configure/app/tools/ts-checker.mdx +7 -23
  3. package/docs/en/guides/advanced-features/page-performance/react-compiler.mdx +42 -27
  4. package/docs/zh/configure/app/source/react-compiler.mdx +72 -0
  5. package/docs/zh/configure/app/tools/ts-checker.mdx +7 -23
  6. package/docs/zh/guides/advanced-features/page-performance/react-compiler.mdx +42 -27
  7. package/package.json +2 -2
package/docs/en/configure/app/source/react-compiler.mdx ADDED
@@ -0,0 +1,72 @@
1
+ ---
2
+ title: reactCompiler
3
+ ---
4
+
5
+ # source.reactCompiler
6
+
7
+ - **Type:** `boolean | ReactCompilerOptions`
8
+ - **Default:** `undefined` (disabled)
9
+
10
+ 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.
11
+
12
+ 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.
13
+
14
+ :::tip
15
+ This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
16
+ :::
17
+
18
+ ## Example
19
+
20
+ ### Enable React Compiler (React 19)
21
+
22
+ ```ts title="modern.config.ts"
23
+ import { defineConfig } from '@modern-js/app-tools';
24
+
25
+ export default defineConfig({
26
+ source: {
27
+ reactCompiler: true,
28
+ },
29
+ });
30
+ ```
31
+
32
+ ### Using with React 18
33
+
34
+ The compiled output targets React 19 by default. To use it in React 18 projects, you need to:
35
+
36
+ 1. Install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) as a **runtime dependency** (the compiled output references it at runtime):
37
+
38
+ ```bash
39
+ npm add react-compiler-runtime
40
+ ```
41
+
42
+ 2. Specify the React version via `target`:
43
+
44
+ ```ts title="modern.config.ts"
45
+ import { defineConfig } from '@modern-js/app-tools';
46
+
47
+ export default defineConfig({
48
+ source: {
49
+ reactCompiler: {
50
+ target: '18',
51
+ },
52
+ },
53
+ });
54
+ ```
55
+
56
+ ### Customize compilation behavior
57
+
58
+ 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:
59
+
60
+ ```ts title="modern.config.ts"
61
+ import { defineConfig } from '@modern-js/app-tools';
62
+
63
+ export default defineConfig({
64
+ source: {
65
+ reactCompiler: {
66
+ compilationMode: 'annotation',
67
+ },
68
+ },
69
+ });
70
+ ```
71
+
72
+ 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).
package/docs/en/configure/app/tools/ts-checker.mdx CHANGED
@@ -81,32 +81,16 @@ export default {
81
81
 
82
82
  > Please refer to [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) for more details.
83
83
 
84
- ## TypeScript Go Support
84
+ ## TypeScript 7+ Support
85
85
 
86
- `tools.tsChecker` supports enabling [TypeScript Go](https://github.com/microsoft/typescript-go) for type checking. This experimental capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and can reduce type-checking time by about 5-10x.
86
+ `tools.tsChecker` supports the native checker included in TypeScript 7+. This capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and can reduce type-checking time on large projects.
87
87
 
88
- Install TypeScript 7.0 RC to enable TypeScript Go automatically:
88
+ Install TypeScript >= 7.0.0 to enable `tsgo` automatically:
89
89
 
90
- <PackageManagerTabs command="install typescript@rc -D" />
90
+ <PackageManagerTabs command="install typescript@latest -D" />
91
91
 
92
- You can also install `@typescript/native-preview` and set `typescript.tsgo` to `true`:
92
+ When `tsgo` is enabled and `typescript.typescriptPath` is set manually, it must point to an absolute TypeScript 7+ `typescript/package.json` path or the legacy `@typescript/native-preview/package.json` path.
93
93
 
94
- <PackageManagerTabs command="install @typescript/native-preview -D" />
94
+ > The `@typescript/native-preview` path is kept only for compatibility. New setups should use TypeScript 7+ from the standard `typescript` package.
95
95
 
96
- ```ts
97
- export default {
98
- tools: {
99
- tsChecker: {
100
- typescript: {
101
- tsgo: true,
102
- },
103
- },
104
- },
105
- };
106
- ```
107
-
108
- When `tsgo` is enabled and `typescript.typescriptPath` is set manually, it must point to an absolute `typescript/package.json` path from TypeScript 7+ or `@typescript/native-preview/package.json`.
109
-
110
- > The `@typescript/native-preview` usage is deprecated and kept only for compatibility. We recommend installing `typescript@rc` to use `tsgo`.
111
-
112
- For supported options and limitations, please refer to [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support).
96
+ For supported options and limitations, please refer to [ts-checker-rspack-plugin - TypeScript 7+ support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-7-support).
package/docs/en/guides/advanced-features/page-performance/react-compiler.mdx CHANGED
@@ -1,54 +1,69 @@
1
1
  # React Compiler
2
2
 
3
- The React Compiler is an experimental compiler introduced in React 19 that can automatically optimize your React code.
3
+ 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`.
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
7
  ## How to Use
8
8
 
9
- ### React 19
9
+ 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`).
10
10
 
11
- If you are using React 19, Modern.js has built-in support for React Compiler, and no additional configuration is required.
11
+ This capability is **disabled by default** and must be enabled explicitly for any React version.
12
12
 
13
- ### React 18
13
+ ### React 19
14
14
 
15
- If you are using React 18, you need to configure it as follows:
15
+ If you are using React 19, simply enable `source.reactCompiler` — no additional dependencies are required:
16
16
 
17
- 1. Install `react-compiler-runtime` to allow the compiled code to run on versions before 19:
17
+ ```ts title="modern.config.ts"
18
+ import { appTools, defineConfig } from '@modern-js/app-tools';
18
19
 
19
- ```bash
20
- npm install react-compiler-runtime
20
+ export default defineConfig({
21
+ source: {
22
+ reactCompiler: true,
23
+ },
24
+ plugins: [appTools()],
25
+ });
21
26
  ```
22
27
 
23
- 2. Install `babel-plugin-react-compiler`:
28
+ ### React 18
29
+
30
+ If you are using React 18, configure it as follows:
31
+
32
+ 1. Install `react-compiler-runtime` as a **runtime dependency** to allow the compiled code to run on versions before React 19:
24
33
 
25
34
  ```bash
26
- npm install babel-plugin-react-compiler
35
+ npm add react-compiler-runtime
27
36
  ```
28
37
 
29
- 3. Register the Babel plugin in your Modern.js configuration file:
38
+ 2. Specify the React version via `target` in the configuration:
30
39
 
31
40
  ```ts title="modern.config.ts"
32
41
  import { appTools, defineConfig } from '@modern-js/app-tools';
33
- import { pluginBabel } from '@rsbuild/plugin-babel';
34
42
 
35
43
  export default defineConfig({
36
- builderPlugins: [
37
- pluginBabel({
38
- babelLoaderOptions: (config, { addPlugins }) => {
39
- addPlugins([
40
- [
41
- 'babel-plugin-react-compiler',
42
- {
43
- target: '18', // 或 '17'，根据你使用的 React 版本
44
- },
45
- ],
46
- ]);
47
- },
48
- });
49
- ];
44
+ source: {
45
+ reactCompiler: {
46
+ target: '18',
47
+ },
48
+ },
50
49
  plugins: [appTools()],
51
50
  });
52
51
  ```
53
52
 
53
+ ## Customize Compilation Behavior
54
+
55
+ `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:
56
+
57
+ ```ts title="modern.config.ts"
58
+ export default defineConfig({
59
+ source: {
60
+ reactCompiler: {
61
+ compilationMode: 'annotation',
62
+ },
63
+ },
64
+ });
65
+ ```
66
+
67
+ 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).
68
+
54
69
  > 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)
package/docs/zh/configure/app/source/react-compiler.mdx ADDED
@@ -0,0 +1,72 @@
1
+ ---
2
+ title: reactCompiler
3
+ ---
4
+
5
+ # source.reactCompiler
6
+
7
+ - **类型：** `boolean | ReactCompilerOptions`
8
+ - **默认值：** `undefined`（不开启）
9
+
10
+ 是否启用 [React Compiler](https://zh-hans.react.dev/learn/react-compiler)。React Compiler 是一个构建期工具，通过自动记忆化（memoization）优化 React 应用的重渲染性能。
11
+
12
+ Modern.js 基于 Rspack `builtin:swc-loader` 内置的 Rust 版 React Compiler 实现该能力（等价于设置 SWC 的 `jsc.transform.reactCompiler`），复用 Rspack 内置的 SWC 转换链，无需额外引入 Babel。
13
+
14
+ :::tip
15
+ 该配置默认关闭，任何 React 版本下都需要显式开启，包括 React 19。
16
+ :::
17
+
18
+ ## 示例
19
+
20
+ ### 开启 React Compiler（React 19）
21
+
22
+ ```ts title="modern.config.ts"
23
+ import { defineConfig } from '@modern-js/app-tools';
24
+
25
+ export default defineConfig({
26
+ source: {
27
+ reactCompiler: true,
28
+ },
29
+ });
30
+ ```
31
+
32
+ ### 在 React 18 中使用
33
+
34
+ React Compiler 编译产物默认面向 React 19。在 React 18 项目中使用时，需要：
35
+
36
+ 1. 将 [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) 安装为**运行时依赖**（编译产物会在运行时引用它）：
37
+
38
+ ```bash
39
+ npm add react-compiler-runtime
40
+ ```
41
+
42
+ 2. 通过 `target` 指定 React 版本：
43
+
44
+ ```ts title="modern.config.ts"
45
+ import { defineConfig } from '@modern-js/app-tools';
46
+
47
+ export default defineConfig({
48
+ source: {
49
+ reactCompiler: {
50
+ target: '18',
51
+ },
52
+ },
53
+ });
54
+ ```
55
+
56
+ ### 自定义编译行为
57
+
58
+ 传入对象时，选项与 Rspack `jsc.transform.reactCompiler` 一致，例如通过 `compilationMode: 'annotation'` 仅编译带有 `"use memo"` 指令的函数：
59
+
60
+ ```ts title="modern.config.ts"
61
+ import { defineConfig } from '@modern-js/app-tools';
62
+
63
+ export default defineConfig({
64
+ source: {
65
+ reactCompiler: {
66
+ compilationMode: 'annotation',
67
+ },
68
+ },
69
+ });
70
+ ```
71
+
72
+ 完整选项请参考 [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) 与 [React Compiler 配置文档](https://zh-hans.react.dev/reference/react-compiler/configuration)。
package/docs/zh/configure/app/tools/ts-checker.mdx CHANGED
@@ -81,32 +81,16 @@ export default {
81
81
 
82
82
  > 请参考 [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) 了解更多用法。
83
83
 
84
- ## TypeScript Go 支持
84
+ ## TypeScript 7+ 支持
85
85
 
86
- `tools.tsChecker` 支持开启 [TypeScript Go](https://github.com/microsoft/typescript-go) 进行类型检查。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，目前仍处于实验阶段，可以将类型检查耗时减少约 5-10 倍。
86
+ `tools.tsChecker` 支持使用 TypeScript 7+ 的原生检查器进行类型检查。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，可以减少大型项目的类型检查耗时。
87
87
 
88
- 安装 TypeScript 7.0 RC 后，TypeScript Go 会自动开启：
88
+ 安装 TypeScript >= 7.0.0 后会自动启用 `tsgo`：
89
89
 
90
- <PackageManagerTabs command="install typescript@rc -D" />
90
+ <PackageManagerTabs command="install typescript@latest -D" />
91
91
 
92
- 你也可以安装 `@typescript/native-preview`，并将 `typescript.tsgo` 设置为 `true`：
92
+ 开启 `tsgo` 后，如果手动设置 `typescript.typescriptPath`，它必须指向 TypeScript 7+ 的 `typescript/package.json` 或旧版 `@typescript/native-preview/package.json` 的绝对路径。
93
93
 
94
- <PackageManagerTabs command="install @typescript/native-preview -D" />
94
+ > `@typescript/native-preview` 路径仅作为兼容保留。新项目应使用标准 `typescript` 包提供的 TypeScript 7+。
95
95
 
96
- ```ts
97
- export default {
98
- tools: {
99
- tsChecker: {
100
- typescript: {
101
- tsgo: true,
102
- },
103
- },
104
- },
105
- };
106
- ```
107
-
108
- 开启 `tsgo` 后，如果手动设置 `typescript.typescriptPath`，它必须指向 TypeScript 7+ 的 `typescript/package.json` 或 `@typescript/native-preview/package.json` 的绝对路径。
109
-
110
- > `@typescript/native-preview` 的用法已废弃，仅作为兼容保留。推荐安装 `typescript@rc` 使用 `tsgo`。
111
-
112
- 关于 `tsgo` 模式下生效的配置项和相关限制，请参考 [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support)。
96
+ 关于 `tsgo` 模式下生效的配置项和相关限制，请参考 [ts-checker-rspack-plugin - TypeScript 7+ support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-7-support)。
package/docs/zh/guides/advanced-features/page-performance/react-compiler.mdx CHANGED
@@ -1,54 +1,69 @@
1
1
  # React Compiler
2
2
 
3
- React Compiler 是 React 19 引入的一个实验性编译器，它可以自动优化你的 React 代码。
3
+ React Compiler 是 React 官方提供的构建期编译器，通过自动记忆化（memoization）减少不必要的重渲染，无需手动编写 `useMemo`、`useCallback` 和 `React.memo`。
4
4
 
5
- 在开始使用 React Compiler 之前，建议阅读 [React Compiler 文档](https://zh-hans.react.dev/learn/react-compiler)，以了解 React Compiler 的功能、当前状态和使用方法。
5
+ 在开始使用 React Compiler 之前，建议阅读 [React Compiler 文档](https://zh-hans.react.dev/learn/react-compiler)，以了解它的功能、当前状态和使用方法。
6
6
 
7
7
  ## 如何使用
8
8
 
9
- ### React 19
9
+ Modern.js 通过 [source.reactCompiler](/configure/app/source/react-compiler) 配置内置支持 React Compiler，底层使用 Rspack `builtin:swc-loader` 中 Rust 实现的 React Compiler，复用 Rspack 内置的 SWC 转换链，无需额外引入 Babel（`babel-plugin-react-compiler`）。
10
10
 
11
- 如果你使用的是 React 19，Modern.js 已内置支持 React Compiler，无需额外配置即可使用。
11
+ 该能力**默认关闭**，任何 React 版本下都需要显式开启。
12
12
 
13
- ### React 18
13
+ ### React 19
14
14
 
15
- 如果你使用的是 React 18，需要按照以下步骤配置：
15
+ 如果你使用的是 React 19，开启 `source.reactCompiler` 即可，无需安装任何额外依赖：
16
16
 
17
- 1. 安装 `react-compiler-runtime`，以允许编译后的代码在 19 之前的版本上运行：
17
+ ```ts title="modern.config.ts"
18
+ import { appTools, defineConfig } from '@modern-js/app-tools';
18
19
 
19
- ```bash
20
- npm install react-compiler-runtime
20
+ export default defineConfig({
21
+ source: {
22
+ reactCompiler: true,
23
+ },
24
+ plugins: [appTools()],
25
+ });
21
26
  ```
22
27
 
23
- 2. 安装 `babel-plugin-react-compiler`：
28
+ ### React 18
29
+
30
+ 如果你使用的是 React 18，需要按照以下步骤配置：
31
+
32
+ 1. 将 `react-compiler-runtime` 安装为**运行时依赖**，以允许编译后的代码在 React 19 之前的版本上运行：
24
33
 
25
34
  ```bash
26
- npm install babel-plugin-react-compiler
35
+ npm add react-compiler-runtime
27
36
  ```
28
37
 
29
- 3. 在你的 Modern.js 配置文件中注册 Babel 插件：
38
+ 2. 在配置中通过 `target` 指定 React 版本：
30
39
 
31
40
  ```ts title="modern.config.ts"
32
41
  import { appTools, defineConfig } from '@modern-js/app-tools';
33
- import { pluginBabel } from '@rsbuild/plugin-babel';
34
42
 
35
43
  export default defineConfig({
36
- builderPlugins: [
37
- pluginBabel({
38
- babelLoaderOptions: (config, { addPlugins }) => {
39
- addPlugins([
40
- [
41
- 'babel-plugin-react-compiler',
42
- {
43
- target: '18', // 或 '17'，根据你使用的 React 版本
44
- },
45
- ],
46
- ]);
47
- },
48
- });
49
- ];
44
+ source: {
45
+ reactCompiler: {
46
+ target: '18',
47
+ },
48
+ },
50
49
  plugins: [appTools()],
51
50
  });
52
51
  ```
53
52
 
53
+ ## 自定义编译行为
54
+
55
+ `source.reactCompiler` 支持传入对象来配置编译行为，选项与 Rspack 的 `jsc.transform.reactCompiler` 一致。例如，通过 `compilationMode: 'annotation'` 可以只编译带有 `"use memo"` 指令的函数，渐进式地启用 React Compiler：
56
+
57
+ ```ts title="modern.config.ts"
58
+ export default defineConfig({
59
+ source: {
60
+ reactCompiler: {
61
+ compilationMode: 'annotation',
62
+ },
63
+ },
64
+ });
65
+ ```
66
+
67
+ 完整选项请参考 [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) 与 [React Compiler 配置文档](https://zh-hans.react.dev/reference/react-compiler/configuration)。
68
+
54
69
  > 详细代码可以参考：[Modern.js & React Compiler 示例项目](https://github.com/web-infra-dev/modern.js/tree/main/examples/react-compiler)
package/package.json CHANGED
@@ -16,14 +16,14 @@
16
16
  "modern",
17
17
  "modern.js"
18
18
  ],
19
- "version": "3.6.0",
19
+ "version": "3.7.0",
20
20
  "publishConfig": {
21
21
  "registry": "https://registry.npmjs.org/",
22
22
  "access": "public"
23
23
  },
24
24
  "dependencies": {
25
25
  "mermaid": "^11.15.0",
26
- "@modern-js/sandpack-react": "3.6.0"
26
+ "@modern-js/sandpack-react": "3.7.0"
27
27
  },
28
28
  "devDependencies": {
29
29
  "rsbuild-plugin-open-graph": "1.1.3",