@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.0 → 3.4.0-ultramodern.2

package/docs/en/configure/app/output/disable-svgr.mdx

@@ -11,6 +11,8 @@ Whether to transform SVGs into React components. If true, will treat all .svg fi
 
 By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting `disableSvgr` to true to improve build performance.
 
+Modern.js runs the built-in SVGR transform through Rsbuild's parallel worker mode when SVGR is enabled.
+
 ```js
 export default {
   output: {

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

@@ -8,7 +8,20 @@ Before starting to use the React Compiler, it is recommended to read the [React
 
 ### React 19
 
-If you are using React 19, Modern.js has built-in support for React Compiler, and no additional configuration is required.
+Modern.js enables Rsbuild's Rust-backed React Compiler integration by default through `builtin:swc-loader`.
+
+To disable it, set `source.reactCompiler` to `false`:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: false,
+  },
+  plugins: [appTools()],
+});
+```
 
 ### React 18
 
@@ -20,33 +33,17 @@ If you are using React 18, you need to configure it as follows:
 npm install react-compiler-runtime
 ```
 
-2. Install `babel-plugin-react-compiler`:
-
-```bash
-npm install babel-plugin-react-compiler
-```
-
-3. Register the Babel plugin in your Modern.js configuration file:
+2. Set the matching React Compiler target in your Modern.js 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', // or '17', depending on the React version you use
+    },
+  },
   plugins: [appTools()],
 });
 ```

package/docs/en/guides/get-started/ultramodern.mdx

@@ -78,6 +78,19 @@ only for local monorepo testing against unreleased packages. Release proof and
 CI should pin the exact cohort with `--ultramodern-package-version` when a
 repo must prove a specific published framework version.
 
+Older repos with Effect BFF entries and `verbatimModuleSyntax` should update to
+the latest BleedingDev cohort instead of adding app-level `"type": "module"`
+metadata, Module Federation shims, or custom server wrappers. The framework BFF
+compiler normalizes CommonJS server output while generated app packages keep
+stable `typescript` for Module Federation DTS generation and use the pinned
+`@typescript/native-preview` toolchain for TS-Go checks.
+
+Cloudflare SSR deploys are also split by runtime responsibility: `.output` is an
+ESM module-worker package, while `.output/worker` remains a CommonJS package
+scope for the worker bundles emitted by Modern.js SSR builds. Do not fix older
+repos by hand-editing generated worker output; upgrade the framework cohort and
+rerun the generated validation instead.
+
 After installing the new cohort, run the generated
 `scripts/validate-ultramodern-workspace.mjs` contract check before accepting
 manual edits. Fix topology, ownership, package-source, local overlay, generated
@@ -202,9 +215,10 @@ Overlays are explicit CodeSmith generators that run after base workspace or
 MicroVertical generation. They extend generated output; they do not replace,
 inherit, or shadow the base templates. The generator and CodeSmith adapter are
 plain Node generator surfaces. The package build emits declaration files through
-the TS-Go toolchain. Generated app packages install the TypeScript 7 RC package
-line and use TS-Go only for local tooling; runtime code does not depend on
-native-preview compiler internals.
+the TS-Go toolchain. Generated app packages keep stable `typescript` for classic
+compiler consumers such as Module Federation DTS generation, while TS-Go uses
+the pinned `@typescript/native-preview` toolchain; runtime code does not depend
+on native-preview compiler internals.
 
 ### Runtime Contracts
 

package/docs/en/guides/topic-detail/module-federation/ssr.mdx

@@ -43,15 +43,22 @@ For production rollout, keep fallback boundaries for remote load failures and mo
 
 ## Node SSR Bundle Compatibility
 
-When Module Federation is enabled together with `server.ssr`, Modern.js automatically switches Node SSR output to a Module Federation compatible mode:
-
-- `target: 'async-node'`
-- `output.module: false`
-- `output.chunkFormat: 'commonjs'`
-- `output.chunkLoading: 'async-node'`
-- `output.library.type: 'commonjs-module'`
-
-This avoids runtime incompatibilities between ESM server output and `@module-federation/node`, and keeps SSR/SSG hydration behavior consistent across host and remote applications.
+When Module Federation is enabled together with `server.ssr`, use the framework
+SSR and Module Federation configuration surfaces instead of forcing bundler
+output by hand. Module Federation application bundles are not a safe place to
+opt into `output.module`; keep MF remotes and hosts on the framework-generated
+MF output mode unless your app has a verified custom runtime contract.
+
+UltraModern generated workspaces keep the root workspace and shared packages as
+ESM, but generated MF app packages intentionally do not add app-level
+`"type": "module"`. Older repos should migrate by upgrading the framework
+cohort and running the generated workspace validation, not by adding app-level
+package mode changes, custom navigation/server wrappers, or Module Federation
+output shims.
+
+For Cloudflare SSR deploys, the outer Worker entry is an ESM module worker while
+copied Modern.js SSR worker bundles stay in a nested CommonJS package scope so
+the module Worker can import the emitted worker bundles consistently.
 
 ## Battle-Tested Rollout Checklist
 

package/docs/en/guides/upgrade/config.mdx

@@ -359,7 +359,9 @@ export default {
 
 ### tools.babel
 
-**Change**: This configuration has been deprecated, the framework no longer includes Babel by default. Please use [Rsbuild's Babel plugin](https://v0.rsbuild.rs/plugins/list/plugin-babel) to enable support.
+**Change**: This configuration has been deprecated, the framework no longer includes Babel by default. Please use [Rsbuild's Babel plugin](https://rsbuild.rs/plugins/list/plugin-babel) to enable support.
+
+When your Babel options are plain serializable data, set `parallel: true` to run Babel through Rsbuild's worker mode. Do not enable it for Babel options that contain functions.
 
 **Migration Example**:
 
@@ -387,6 +389,7 @@ export default {
   // ...
   builderPlugins: [
     pluginBabel({
+      parallel: true,
       babelLoaderOptions: {
         plugins: [
           [

package/docs/zh/configure/app/output/disable-svgr.mdx

@@ -12,6 +12,8 @@ title: disableSvgr
 默认情况下，在 JS 文件中引用 SVG 资源时，Modern.js 会调用 SVGR，将 SVG 图片转换为一个 React 组件。
 如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用时，可以通过将 `disableSvgr` 设置为 true 来关闭此项转换，以提升构建性能。
 
+启用 SVGR 时，Modern.js 会通过 Rsbuild 的并行 worker 模式运行内置 SVGR 转换。
+
 ```js
 export default {
   output: {

package/docs/zh/guides/advanced-features/page-performance/react-compiler.mdx

@@ -8,7 +8,20 @@ React Compiler 是 React 19 引入的一个实验性编译器，它可以自动
 
 ### React 19
 
-如果你使用的是 React 19，Modern.js 已内置支持 React Compiler，无需额外配置即可使用。
+Modern.js 默认通过 `builtin:swc-loader` 启用 Rsbuild 的 Rust 版 React Compiler 集成。
+
+如果需要关闭，可以将 `source.reactCompiler` 设置为 `false`：
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: false,
+  },
+  plugins: [appTools()],
+});
+```
 
 ### React 18
 
@@ -20,33 +33,17 @@ React Compiler 是 React 19 引入的一个实验性编译器，它可以自动
 npm install react-compiler-runtime
 ```
 
-2. 安装 `babel-plugin-react-compiler`：
-
-```bash
-npm install babel-plugin-react-compiler
-```
-
-3. 在你的 Modern.js 配置文件中注册 Babel 插件：
+2. 在 Modern.js 配置中设置匹配的 React Compiler target：
 
 ```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', // 或 '17'，根据你使用的 React 版本
+    },
+  },
   plugins: [appTools()],
 });
 ```

package/docs/zh/guides/get-started/ultramodern.mdx

@@ -76,6 +76,12 @@ mise exec -- pnpm build
 联调未发布包。发布证明和 CI 如果需要证明某个已发布框架版本，应使用
 `--ultramodern-package-version` 固定精确 cohort。
 
+带有 Effect BFF 入口和 `verbatimModuleSyntax` 的旧仓库，应升级到最新的
+BleedingDev cohort，而不是给 app package 增加 `"type": "module"`、Module
+Federation shim 或自定义 server wrapper。框架 BFF compiler 会把服务端输出规范化为
+CommonJS，同时生成的 app package 继续为 Module Federation DTS 保留稳定的
+`typescript`，并使用固定的 `@typescript/native-preview` 工具链执行 TS-Go 检查。
+
 安装新 cohort 后，先运行生成的
 `scripts/validate-ultramodern-workspace.mjs` 契约校验，再接受人工改动。topology、
 ownership、package-source、本地 overlay、生成契约、Tailwind prefix 或 Module
@@ -189,8 +195,9 @@ JSON 契约缺失或不是对象、Tailwind 前缀冲突，都会报告归属契
 Overlays 是显式配置的 CodeSmith 生成器，会在基础 workspace 或 MicroVertical
 生成之后运行。它们只扩展生成结果，不替换、不继承、也不遮蔽基础模板。公开生成器与
 CodeSmith adapter 都是普通 Node 生成器入口。包构建通过 TS-Go 工具链产出声明文件；
-生成出来的 app package 直接安装 TypeScript 7 RC 包线，并且只在本地工具链中使用
-TS-Go，运行时代码不依赖 native-preview compiler 内部实现。
+生成出来的 app package 为 Module Federation DTS 等传统 compiler consumer 保留稳定的
+`typescript`，TS-Go 则使用固定的 `@typescript/native-preview` 工具链；运行时代码不依赖
+native-preview compiler 内部实现。
 
 ### 运行时契约
 

package/docs/zh/guides/topic-detail/module-federation/ssr.mdx

@@ -41,15 +41,21 @@ export default defineConfig({
 
 ## Node SSR 打包兼容性
 
-当开启 Module Federation 并同时开启 `server.ssr` 时，Modern.js 会自动将 Node SSR 构建切换到 Module Federation 兼容模式：
-
-- `target: 'async-node'`
-- `output.module: false`
-- `output.chunkFormat: 'commonjs'`
-- `output.chunkLoading: 'async-node'`
-- `output.library.type: 'commonjs-module'`
-
-这样可以避免 ESM 服务端产物与 `@module-federation/node` 运行时之间的兼容性问题，并保证 host / remote 在 SSR 与 SSG 场景下的 hydration 行为一致。
+当同时开启 Module Federation 与 `server.ssr` 时，请使用框架提供的 SSR
+和 Module Federation 配置入口，不要在应用里手动强制 bundler 输出模式。
+Module Federation 应用级 bundle 不是安全开启 `output.module` 的位置；除非
+应用已经验证了自定义运行时契约，否则 host 与 remote 都应保留框架生成的
+MF 输出模式。
+
+UltraModern 生成的 workspace root 和共享包保持 ESM，但生成的 MF app
+package 会有意不添加 app 级 `"type": "module"`。旧仓库迁移时应升级到
+新的框架 cohort，并运行生成的 workspace 校验；不要通过添加 app 级
+package mode、定制 server/navigation wrapper 或 Module Federation 输出 shim
+来绕过框架问题。
+
+Cloudflare SSR 部署中，最外层 Worker entry 是 ESM module worker；复制出的
+Modern.js SSR worker bundle 则保留在内层 CommonJS package scope 中，确保
+module Worker 可以稳定 import 这些已生成的 worker bundle。
 
 ## Battle-Tested 上线检查清单
 

package/docs/zh/guides/upgrade/config.mdx

@@ -359,7 +359,9 @@ export default {
 
 ### tools.babel
 
-**变更内容**：该配置已废弃，框架不再内置 Babel，请使用 [Rsbuild 的 Babel 插件](https://v0.rsbuild.rs/plugins/list/plugin-babel) 来启用支持。
+**变更内容**：该配置已废弃，框架不再内置 Babel，请使用 [Rsbuild 的 Babel 插件](https://rsbuild.rs/plugins/list/plugin-babel) 来启用支持。
+
+当 Babel 选项都是可序列化的普通数据时，可以设置 `parallel: true`，通过 Rsbuild 的 worker 模式运行 Babel。包含函数的 Babel 选项不要启用该模式。
 
 **迁移示例**：
 
@@ -387,6 +389,7 @@ export default {
   // ...
   builderPlugins: [
     pluginBabel({
+      parallel: true,
       babelLoaderOptions: {
         plugins: [
           [

package/package.json

@@ -19,23 +19,23 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.4.0-ultramodern.0",
+  "version": "3.4.0-ultramodern.2",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.0"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.2"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "2.0.0",
     "@rspress/core": "2.0.14",
     "@rspress/plugin-llms": "2.0.14",
     "@rspress/shared": "2.0.14",
-    "@shikijs/transformers": "^4.2.0",
+    "@shikijs/transformers": "^4.3.0",
     "@types/fs-extra": "11.0.4",
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.0.1",
     "@typescript/native-preview": "7.0.0-dev.20260624.1",
     "classnames": "^2.5.1",
     "clsx": "^2.1.1",