@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

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

@@ -6,7 +6,7 @@
 
 ## Module Federation 2.0
 
-Module Federation 作为 Webpack 5 推出的重磅功能，自发布以来已经三年有余。在今年，字节跳动与 Module Federation 的作者 [@Zack Jackson](https://github.com/ScriptedAlchemy) 以及社区成员共同推出了 **Module Federation 2.0**。
+Module Federation 作为 Webpack 5 推出的重磅功能，自发布以来已经五年有余。在今年，字节跳动与 Module Federation 的作者 [@Zack Jackson](https://github.com/ScriptedAlchemy) 以及社区成员共同推出了 **Module Federation 2.0**。
 
 Module Federation 2.0 基于字节跳动内部实践以及 Module Federation 原有社区生态，解决了原先版本中的诸多问题。
 
@@ -20,7 +20,7 @@ Module Federation 2.0 基于字节跳动内部实践以及 Module Federation 原
 
 基于字节跳动内部实践，Module Federation 团队官方提供了 [Modern.js 插件](https://www.npmjs.com/package/@module-federation/modern-js)，帮助开发者更方便的使用 Module Federation。
 
-插件会识别当前构建引擎（Webpack 或 Rspack），在 Modern.js 应用中注入 Module Federation 对应插件，并自动处理构建配置、添加运行时代码等。
+插件会在 Modern.js 应用中注入 Module Federation 插件，并自动处理构建配置、添加运行时代码等。
 
 同时，插件还支持在 Modern.js SSR 应用中使用 Module Federation，提供更好的性能体验。
 
@@ -30,6 +30,6 @@ Module Federation 2.0 基于字节跳动内部实践以及 Module Federation 原
 
 **应用级别模块**是具备应用的框架渲染能力及路由能力，能像应用一样运行的模块。应用级别模块是在**微前端框架**中非常重要的能力，提供跨应用框架（React、Vue）加载和渲染的能力，支持加载带路由的模块。
 
-Module Federation 2.0 提供了 [Bridge](https://module-federation.io/zh/practice/bridge/index.html) 的能力，用于加载应用级别模块。
+Module Federation 2.0 提供了 [Bridge](https://module-federation.io/zh/practice/bridge/overview.html) 的能力，用于加载应用级别模块。
 
-Modern.js 基于 Brdige 和自身内部实现提供了 API，可以非常简单的导出应用级别模块。详细内容可以参考 [应用级别模块](/guides/topic-detail/module-federation/application)。
+Modern.js 基于 Brdige 和自身内部实现提供了 API，可以非常简单的导出应用级别模块。详细内容可以参考 [应用级别模块](/guides/topic-detail/module-federation/application)。

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

@@ -13,17 +13,15 @@ export default defineConfig({
   server: {
     ssr: {
       mode: 'stream',
-      // 禁用预渲染，优化 SSR 性能
-      disablePrerender: true,
     },
   },
-})
+});
 ```
 
 为更好的性能体验，我们仅支持 Streaming SSR 情况使用这种能力组合。
 
 :::warning
-目前 `@module-federation/bridge-react` 未兼容 Node 环境，你必须从依赖中移除它，才能正常使用 Module Federation 和服务端渲染。这意味着 Bridge 无法和服务端渲染配合使用。
+应用级别模块（使用 `createBridgeComponent` 和 `createRemoteAppComponent` 的模块）不支持服务端渲染（SSR）。如果你需要使用 SSR 功能，请使用组件级别的模块导出方式。
 :::
 
 ## 数据获取
@@ -58,7 +56,6 @@ export const fetchData = async (params: DataFetchParams): Promise<Data> => {
 
 ```ts title="src/components/Button.tsx"
 import React from 'react';
-import './index.css';
 import type { Data } from './Button.data';
 
 export const Button = (props: { mfData: Data }) => {
@@ -70,3 +67,52 @@ export const Button = (props: { mfData: Data }) => {
   );
 };
 ```
+
+## 消费组件
+
+消费者必须使用 [`createLazyComponent`](https://module-federation.io/zh/practice/bridge/react-bridge/load-component.html#createlazycomponent-api-%E5%8F%82%E8%80%83) 的方式加载远程组件，并指定 export 为 'default'。
+
+```tsx title="src/routes/page.tsx"
+import type { JSX } from 'react';
+import { getInstance } from '@module-federation/modern-js/runtime';
+import {
+  ERROR_TYPE,
+  lazyLoadComponentPlugin,
+} from '@module-federation/modern-js/react';
+
+const instance = getInstance();
+instance!.registerPlugins([lazyLoadComponentPlugin()]);
+
+const Button = instance!.createLazyComponent({
+  loader: () => {
+    return import('remote/Button');
+  },
+  loading: 'loading...',
+  export: 'Button', // 这里需要配置为远程组件的 export 名称
+  fallback: ({ error, errorType, dataFetchMapKey }) => {
+    console.error(error);
+    if (errorType === ERROR_TYPE.LOAD_REMOTE) {
+      return <div>load remote failed</div>;
+    }
+    if (errorType === ERROR_TYPE.DATA_FETCH) {
+      return (
+        <div>
+          data fetch failed, the dataFetchMapKey key is: {dataFetchMapKey}
+        </div>
+      );
+    }
+    return <div>error type is unknown</div>;
+  },
+});
+
+const Index = (): JSX.Element => {
+  return (
+    <div>
+      <h1>Basic usage with data fetch</h1>
+      <Button />
+    </div>
+  );
+};
+
+export default Index;
+```

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

@@ -21,17 +21,8 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 import { moduleFederationPlugin } from '@module-federation/modern-js';
 
 export default defineConfig({
-  runtime: {
-    router: true,
-  },
-  plugins: [
-    appTools({
-      bundler: 'rspack',
-    }),
-    moduleFederationPlugin(),
-  ],
+  plugins: [appTools(), moduleFederationPlugin()],
 });
-
 ```
 
 ## 生产者导出模块
@@ -70,7 +61,7 @@ export default createModuleFederationConfig({
 ```
 
 :::tip
-在上述代码块中，我们为 Module Federation 导出的 manifest 和 remoteEntry.js 都设置了 `static` 前缀，这是因为 Modern.js 要求将所有需要暴露的资源都放在 `static/` 目录下，Modern.js 的服务器在生产环境时也只会托管 `static/` 目录。
+在上述代码块中，我们为 Module Federation 导出的 `manifest` 和 `remoteEntry.js` 都设置了 `static` 前缀，这是因为 Modern.js 要求将所有需要暴露的资源都放在 `static/` 目录下，Modern.js 的服务器在生产环境时也只会托管 `static/` 目录。
 :::
 
 另外，我们还需要修改 `modern.config.ts`，为生产者提供一个开发环境的端口，让消费者可以通过此端口访问生产者的资源：
@@ -80,18 +71,10 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 import { moduleFederationPlugin } from '@module-federation/modern-js';
 
 export default defineConfig({
-  dev: {
+  server: {
     port: 3051,
   },
-  runtime: {
-    router: true,
-  },
-  plugins: [
-    appTools({
-      bundler: 'rspack',
-    }),
-    moduleFederationPlugin(),
-  ],
+  plugins: [appTools(), moduleFederationPlugin()],
 });
 ```
 
@@ -121,7 +104,7 @@ export default createModuleFederationConfig({
 我们创建新的路由文件 `src/routes/remote/page.tsx`，引入生产者模块：
 
 ```tsx title="src/routes/remote/page.tsx"
-import React, { useState, Suspense } from 'react';
+import React, { Suspense, type JSX } from 'react';
 import { Button } from 'remote/Button';
 
 const Index = (): JSX.Element => {
@@ -194,25 +177,21 @@ export default defineConfig({
   server: {
     port: 3051,
   },
-  runtime: {
-    router: true,
-  },
   output: {
     // Now this configuration is only used in the local when you run modern serve command.
     // If you want to deploy the application to the platform, use your own domain name.
     // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
     assetPrefix: 'http://127.0.0.1:3051',
   },
-  plugins: [
-    appTools({
-      bundler: 'rspack', // Set to 'webpack' to enable webpack
-    }),
-    moduleFederationPlugin(),
-  ],
+  plugins: [appTools(), moduleFederationPlugin()],
 });
 ```
 
-现在，在生产者中运行 `modern build && modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
+现在，在生产者中运行 `modern build && MODERN_MF_AUTO_CORS=true modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
+
+:::tip
+在使用 `modern serve` 命令时，需要在启动生产者项目时携带 `MODERN_MF_AUTO_CORS=true` 环境变量，以自动处理跨域问题，确保消费者可以正常访问生产者的远程模块资源。
+:::
 
 上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base)。
 

package/docs/zh/guides/troubleshooting/builder.mdx

@@ -18,21 +18,9 @@ Modern.js 内部基于 [Rsbuild](https://rsbuild.rs/) 封装了自身的构建
 
 ---
 
-### 如何清空 webpack 编译缓存？
+### 如何查看最终生成的 Rspack 配置?
 
-默认情况下，Modern.js 的 webpack 编译缓存生成在 `./node_modules/.cache/webpack` 目录下。
-
-如果需要清空本地的编译缓存，可以执行以下命令：
-
-```bash
-rm -rf ./node_modules/.cache
-```
-
----
-
-### 如何查看最终生成的 webpack / Rspack 配置?
-
-Modern.js 提供 [inspect 命令](/apis/app/commands.html) 用于查看项目最终生成的 Modern.js 配置以及 webpack / Rspack 配置。
+Modern.js 提供 [inspect 命令](/apis/app/commands.html) 用于查看项目最终生成的 Modern.js 配置以及 Rspack 配置。
 
 ```bash
 ➜ npx modern inspect
@@ -43,34 +31,6 @@ Inspect config succeed, open following files to view the content:
   - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
 ```
 
----
-
-### webpack 编译出现 'compilation' argument 报错？
-
-如果编译时出现以下报错，通常是由于项目中安装了错误的 webpack 版本，或者安装了多个 webpack 版本引起：
-
-```bash
-TypeError: The 'compilation' argument must be an instance of Compilation
-```
-
-webpack 版本问题有以下几种情况：
-
-1. 项目的 package.json 中直接声明了 webpack 依赖，并且与 Modern.js 依赖的 webpack 版本范围不同，无法匹配到同一个版本。
-2. 项目里安装的多个 npm 包都依赖了 webpack，并且它们依赖的 webpack 版本范围不同，无法匹配到同一个版本。
-3. 由于包管理器的 lock 机制，导致 lock 文件中产生了多个 webpack 版本。
-
-如果是第一种情况，建议从项目的 package.json 中移除 webpack 依赖。因为 Modern.js 默认封装了 webpack 相关能力，并且会在 [tools.webpack](/configure/app/tools/webpack.html) 配置项中传入 webpack 对象。因此在大多数情况下，不建议在项目中额外安装 webpack 依赖。
-
-如果是第二种情况，建议看看能否升级某个 npm 包，使其依赖的 webpack 版本范围与 Modern.js 保持一致。也可以通过包管理器的能力来手动统一版本，比如使用 [yarn resolutions](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) 或 [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides)。
-
-如果是第三种情况，可以使用第二种情况中提到的两种方法，也可以尝试删除 lock 文件后重新安装来解决。
-
-:::tip
-删除 lock 文件会使项目中的依赖版本自动升级到指定范围下的最新版，请进行充分的测试。
-:::
-
----
-
 ### 在 Monorepo 中引用其他模块，代码没有被正确编译？
 
 出于编译性能的考虑，默认情况下，Modern.js 不会编译 `node_modules` 下的文件，也不会编译当前工程目录外部的文件。
@@ -124,7 +84,7 @@ Error: ES Modules may not assign module.exports or exports.*, Use ESM export syn
 
 ### 编译进度条卡死，但终端无 Error 日志？
 
-当编译进度条卡死，但终端无 Error 日志时，通常是因为编译过程中出现了异常。在某些情况下，当 Error 被 webpack 或其他模块捕获后，错误日志不会被正确输出。最为常见的场景是 Babel 配置出现异常，抛出 Error 后被 webpack 捕获，而 webpack 在个别情况下吞掉了 Error。
+当编译进度条卡死，但终端无 Error 日志时，通常是因为编译过程中出现了异常。在某些情况下，当 Error 被构建工具或其他模块捕获后，错误日志不会被正确输出。最为常见的场景是 Babel 配置出现异常，抛出 Error 后被构建工具捕获，而构建工具在个别情况下吞掉了 Error。
 
 **解决方法：**
 
@@ -188,47 +148,6 @@ export default {
 };
 ```
 
-除了上述原因外，还有一种可能会导致 Babel 编译卡死，就是使用 Babel 编译了一个超过 1 万行的大型 JS 文件（通常是使用 `source.include` 编译了 node_modules 中的某个大文件）。
-
-当 Babel 编译大文件时，Modern.js 内置的 babel-plugin-styled-components 会卡死，社区中已有 [相关 issue](https://github.com/styled-components/babel-plugin-styled-components/issues/374)。
-
-未来 Modern.js 会考虑移除内置的 babel-plugin-styled-components。在当前版本里，你可以将 [tools.styledComponents](/configure/app/tools/styled-components.html) 设置为 `false` 来移除该插件。
-
-```ts title="modern.config.ts"
-export default {
-  tools: {
-    styledComponents: false,
-  },
-};
-```
-
----
-
-### webpack 编译缓存未生效，应该如何排查？
-
-Modern.js 默认开启了 webpack 的持久化缓存。
-
-首次编译完成后，会自动生成缓存文件，并输出到 `./node_modules/.cache/webpack` 目录下。执行第二次编译时，会命中缓存，并大幅度提高编译速度。
-
-当 `package.json` 等配置文件被修改时，缓存会自动失效。
-
-如果项目中 webpack 编译缓存一直未生效，可以添加以下配置进行排查：
-
-```ts
-export default {
-  tools: {
-    webpack(config) {
-      config.infrastructureLogging = {
-        ...config.infrastructureLogging,
-        debug: /webpack\.cache/,
-      };
-    },
-  },
-};
-```
-
-添加以上配置后，webpack 会输出日志用于 debug，请参考 `PackFileCacheStrategy` 相关的日志来了解缓存失效的原因。
-
 ---
 
 ### 从 lodash 中引用类型后出现编译报错？

package/docs/zh/guides/troubleshooting/cli.mdx

@@ -6,11 +6,9 @@ sidebar_position: 2
 
 ### 使用 pnpm 时无法正确传递命令行参数？
 
-pnpm v6 和 pnpm v7 版本在执行命令时使用姿势不完全一致，需要注意以下事项：
+在使用 pnpm 调用 `package.json` 中的命令时，需要注意参数传递的方式：
 
-pnpm v7：
-
-在使用 pnpm 调用 `package.json` 中的命令时，如果需要传递参数至 pnpm，需要将参数放到命令前。
+- **如果需要传递参数至 pnpm**，需要将参数放到命令前。
 
 例如使用 pnpm `--filter` 参数执行 prepare 命令：
 
@@ -18,7 +16,7 @@ pnpm v7：
 pnpm run --filter "./packages/**" prepare
 ```
 
-如果需要传递参数至命令，需要将参数放到命令后。
+- **如果需要传递参数至命令**，需要将参数放到命令后。
 
 例如，在如下 `package.json` 配置中：
 
@@ -36,28 +34,6 @@ pnpm run --filter "./packages/**" prepare
 pnpm run command --options
 ```
 
-pnpm v6:
-
-在如下 `package.json` 配置中：
-
-```json
-{
-  "scripts": {
-    "command": "modern command"
-  }
-}
-```
-
-当需要执行 `modern command --option`：
-
-使用 pnpm 时，需要执行 `pnpm run command -- --option`。
-
-这是因为 pnpm 对于命令参数的处理与 Yarn 并不相同，但是与 npm 类似：在不加 `--` 字符串的时候，传递的是 pnpm 的参数；在使用 `--` 字符串的时候，传递的是执行脚本的参数。
-
-在上述例子里参数 `--option` 传递给了 `modern command`。如果执行 `pnpm run command --option`，则参数 `--option` 将传递给 pnpm。
-
-总结来说：
-
-**在使用 pnpm v7 时，如果传递参数给 pnpm，需要将参数放置到命令前**。
-
-**在使用 pnpm v6 时，如果传递的参数给 pnpm，不需要加 `--`；如果传递的参数是给脚本使用，需要增加 `--` 字符串**。
+:::tip
+Modern.js 要求 Node.js >= 20.19.5，而 pnpm v6 不支持 Node.js 20，因此请使用 pnpm v7 或更高版本。
+:::

package/docs/zh/guides/troubleshooting/dependencies.mdx

@@ -14,24 +14,24 @@ sidebar_position: 1
 
 对于使用 npm 或 yarn 的项目，可以使用 `npm ls` 命令。
 
-比如执行 `npm ls @modern-js/core`，可以看到如下结果：
+比如执行 `npm ls @modern-js/plugin`，可以看到如下结果：
 
 ```
 project
 └─┬ @modern-js/app-tools@x.y.z
-  └── @modern-js/core@x.y.z
+  └── @modern-js/plugin@x.y.z
 ```
 
 **pnpm**
 
 对于使用 pnpm 的项目，可以使用 `pnpm ls` 命令。
 
-比如执行 `pnpm ls @modern-js/core --depth Infinity`，可以看到如下结果：
+比如执行 `pnpm ls @modern-js/plugin --depth Infinity`，可以看到如下结果：
 
 ```
 devDependencies:
 @modern-js/app-tools x.y.z
-└── @modern-js/core x.y.z
+└── @modern-js/plugin x.y.z
 ```
 
 ---
@@ -43,24 +43,24 @@ devDependencies:
 ```bash
 The engine "node" is incompatible with this module.
 
-Expected version ">=16.2.0". Got "12.20.1"
+Expected version ">=20.19.5". Got "16.20.1"
 ```
 
-使用 Modern.js 时，建议使用 [Node.js 18.x](https://nodejs.org/download/release/latest-v18.x/) 的最新版本。
+Modern.js 要求 Node.js 版本 >= 20.19.5，我们强烈推荐使用最新的 LTS 版本（如 [Node.js 22 LTS](https://nodejs.org/)）以获得最佳体验。
 
 如果当前环境的 Node.js 版本低于上述要求的版本，则可以使用 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 等工具进行版本切换。
 
 下面是使用 nvm 的示例：
 
-```
-# 安装 Node.js v14
-nvm install 14
+```bash
+# 安装 Node.js 22 LTS
+nvm install 22 --lts
 
-# 切换到 Node 14
-nvm use 14
+# 切换到 Node.js 22
+nvm use 22
 
-# 将 Node 14 设置为默认版本
-nvm default 14
+# 将 Node.js 22 设置为默认版本
+nvm alias default 22
 ```
 
 在本地开发环境推荐使用 [fnm](https://github.com/Schniz/fnm)，它的用法与 nvm 相似，但拥有比 nvm 更好的性能。
@@ -77,14 +77,14 @@ Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/r
 Type '{}' is not assignable to type 'ReactNode'.
 ```
 
-出现这个问题的原因是 React 18 与 React 16/17 中的 ReactNode 类型定义不同，如果项目中出现多个不同 `@types/react` 版本，就会出现 ReactNode 类型冲突，导致以上报错。
+出现这个问题的原因是 React 18+ 与 React 16/17 中的 ReactNode 类型定义不同，如果项目中出现多个不同 `@types/react` 版本，就会出现 ReactNode 类型冲突，导致以上报错。
 
-解决方法为将项目中的 `@types/react` 和 `@types/react-dom` 锁定在统一的版本上，比如 `v17`。
+解决方法为将项目中的 `@types/react` 和 `@types/react-dom` 锁定在统一的版本上，比如 `v19`。
 
 ```json
 {
-  "@types/react": "^17",
-  "@types/react-dom": "^17"
+  "@types/react": "^19",
+  "@types/react-dom": "^19"
 }
 ```
 
@@ -102,12 +102,10 @@ Type '{}' is not assignable to type 'ReactNode'.
 
 ### Modern.js 框架最低支持的 React 版本是多少？
 
-**Modern.js 框架推荐使用的 React 版本为 >= 18.0.0**，并且不同功能对 React 版本的要求有所不同。
+**Modern.js 框架要求使用的 React 版本为 >= 18.0.0**。
 
-- 如果你在使用 React 17，那么部分框架功能将无法使用，比如 Streaming SSR，因为它依赖 React 18 提供的新特性。
-- 如果你仍然在使用 React 16，那么将无法使用 Modern.js 的运行时或服务端能力。你可以考虑使用 Modern.js 的构建模式，即只使用 Modern.js 的构建能力，这种情况可以继续使用 React 16。
-
-在 Modern.js 未来的 major 版本中，我们会逐步移除对 React 16 和 React 17 的支持。因此，请尽快升级到 React 18 以上版本。
+- **如果使用 Modern.js 的 runtime 能力**（包括 SSR、Streaming SSR、数据加载、路由等），必须使用 React 18 或更高版本。React 16 和 React 17 不再支持。
+- **如果仅使用 Modern.js 的构建能力**（不使用 runtime），理论上可以使用 React 16 或 React 17，但强烈建议升级到 React 18 以上版本以获得最佳体验和完整功能支持。
 
 ---
 
@@ -118,6 +116,8 @@ Type 'CliPlugin<{}, {}, {}, {}>' is not assignable to type 'CliPlugin<any, {}, {
   Types of property 'setup' are incompatible.
 ```
 
-当你在使用 Modern.js 框架时配置文件出现以上报错，可能是由于 Modern.js 相关包的版本号未统一导致。可以通过 `npx modern upgrade` 命令对 modern.js 依赖进行升级和版本统一。
+当你在使用 Modern.js 框架时配置文件出现以上报错，可能是由于 Modern.js 相关包的版本号未统一导致。需要手动将所有 `@modern-js/**` 包的版本统一更新到相同版本。
 
 在 monorepo 中由于不同子项目所用的 Modern.js 框架版本不一致也可能出现以上问题。
+
+关于如何统一升级依赖版本，请参考[版本升级](/guides/get-started/upgrade)文档。

package/docs/zh/guides/upgrade/_meta.json

@@ -0,0 +1 @@
+["overview", "config", "entry", "web-server", "tailwindcss", "other"]