@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,80 @@
+---
+title: UltraModern.js
+sidebar_position: 2
+---
+
+# UltraModern.js v3 与 Modern.js v3 对比
+
+本文对比 **UltraModern.js v3** 与 **Modern.js v3**（基线：`v3.0.2`）。
+
+UltraModern.js 在这里更像是“更强默认值的 Modern.js 配置档案”这一参考名词：目标是在不把 Modern.js 分叉成另一套框架的前提下，为 Super App / ERP 场景加固默认基线。
+
+## 设计原则
+
+- 差异要小且明确。
+- 保持上游 Modern.js 的心智模型与可持续回灌能力。
+- 仅在跨团队稳定性场景增加平台契约。
+- 保留按应用关闭和显式兼容分支的能力。
+
+## 兼容性承诺
+
+UltraModern.js v3 保持以下不变：
+
+- Modern.js 的应用/配置/插件心智模型。
+- 既有项目结构与命令使用方式。
+- 渐进式接入路径（应用无需大规模重构）。
+
+UltraModern 的增强能力会尽量以“更强默认值”“显式兼容分支”或“可审计 gate”的形式落地，而不是演化成另一套独立产品面。
+
+## 有意引入的差异（v3 线）
+
+| 领域 | Modern.js v3 基线 | UltraModern.js v3 |
+| --- | --- | --- |
+| 构建诊断能力 | RsDoctor 多为显式开启 | 新增 `performance.rsdoctor`，并在 Rspack 生产构建默认开启，同时产出 `.rsdoctor/ultramodern-diagnostics.json` 契约文件 |
+| 输出与静态资源回源 | 预压缩策略通常由业务自定义 | 默认开启 `output.precompress`，并按 `Accept-Encoding` 协商 `.br` / `.gz` 回源 |
+| BFF 运行时与契约 | 提供标准 BFF 运行时与客户端生成能力 | 增加 `requestId` 维度隔离、初始化 fail-fast 校验与操作/追踪关联 Header |
+| BFF 运行时选型 | Modern.js v3 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-first 契约与 MF failure-injection 覆盖 |
+| Telemetry 标准化 | 可观测链路通常由业务侧自行拼装 | 增加框架级 telemetry 管线，内置 OTLP/VictoriaMetrics，支持脱敏、批处理与背压 |
+| 应用级 MF SSR 协议 | 没有以 super-app 为重点的应用级稳定性契约开关 | 增加 `server.ssr.moduleFederationAppSSR` 配置/环境变量握手，并补齐集成级回归保障 |
+| MF 远程加载可靠性 | 重试/降级策略通常由各业务单独实现 | 增加 timeout/network/contract-error 的确定性可靠性矩阵与分布式 OTEL 连续性断言 |
+| 模块准入治理 | 基线无模块认证证据化 gate profile | 新增模块 SDK 契约、边界反模式守卫与发布/模块认证 gate 工作流 |
+| 路由运行时 | 默认运行时路径以 React Router 为中心 | 增加 TanStack Router 运行时/CLI 一等支持（React Router 继续可用） |
+| 脚手架模板 | 默认 create 模板以 React Router 起步路径为中心 | 增加 TanStack-ready 与 Tailwind-ready 的 create 模板 |
+| Starter 预设约束 | 生成应用默认没有 UltraModern 预设 gate 工作流 | 生成脚手架会附带 `ultramodern:check`、可关闭的 env 开关，以及 `.github/workflows/ultramodern-gates.yml` |
+
+## 我们刻意不做的事情
+
+- 不将核心架构分叉成另一套不兼容框架模型。
+- 不强制替换普通 Modern.js 团队已稳定使用的默认行为。
+- 运行时保持 `effect` 与 `hono` 双模式并存，但不提供隐式回退。
+- 除非稳定性硬需求，否则避免引入破坏性 API 变更。
+
+## 迁移说明
+
+对于已经在使用 Modern.js v3 的团队，迁移路径依然是“兼容优先”：保持 Modern.js 的心智模型不变，逐步向 MV-first / TanStack-first / Effect-first 默认方向收敛，同时把兼容分支明确保留下来。
+
+1. 既有 React Router 应用可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，但 React Router 兼容分支仍然保留，团队可以按自己的节奏迁移。
+2. 新建或迁移中的 BFF 能力优先使用 `bff.runtimeFramework: 'effect'`，并将入口实现放在 `api/effect/index.ts`。如果当前应用已经在 `api/lambda/**` 下使用 Hono 处理函数，就继续显式使用 `bff.runtimeFramework: 'hono'`，等准备好再迁移；Hono 仍是受支持的兼容分支。
+3. 将基线契约视为渐进式默认值，而不是一次性强制切换。`MODERN_BASELINE_ENABLE_MF_SSR`、`MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` 和 `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` 已经提供了按应用、按环境关闭的能力，方便在收敛到目标栈之前逐步过渡。
+4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成脚手架也会自带 `.github/workflows/ultramodern-gates.yml`，因此 `pnpm run ultramodern:check` 与 `pnpm run build` 从第一天开始就是接入契约的一部分。
+
+## 基线开关（可按需关闭）
+
+生成的 `presetUltramodern(...)` 脚手架会开启更严格的平台契约。以下环境变量会在生成的 `modern.config.ts` 中读取，可按应用或按环境关闭/覆盖：
+
+- `MODERN_BASELINE_ENABLE_MF_SSR`（默认：`true`）：开启应用级 MF SSR 基线契约（`server.ssr.mode: 'stream'` + `moduleFederationAppSSR`）。应用不使用 app-level MF SSR 或希望先走普通 SSR/CSR 路径时可关闭。
+- `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`（默认：`true`）：开启默认 BFF producer 身份契约（`bff.requestId`）。应用不需要跨项目 producer 隔离时可关闭。
+- `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS`（默认：`true`）：在基线配置中启用 telemetry 导出器。当前环境还没有 telemetry 后端时可关闭。
+- `MODERN_BASELINE_APP_ID`（默认：`basename(process.cwd())`）：覆盖基线 `bff.requestId` 身份。需要固定、可治理的统一 producer ID 命名时建议设置。
+- `MODERN_TELEMETRY_OTLP_ENDPOINT`（默认：`http://127.0.0.1:4318/v1/logs`）：OTLP 导出端点。接入其他 OTLP collector 地址时覆盖。
+- `MODERN_TELEMETRY_VICTORIA_ENDPOINT`（默认：`http://127.0.0.1:8428/api/v1/import/prometheus`）：VictoriaMetrics 导出端点。接入其他 VM 写入地址时覆盖。
+- `MODERN_TELEMETRY_FAIL_LOUD_STARTUP`（默认：`true`）：导出器健康检查失败时启动即失败（fail-loud）。本地/开发环境希望 telemetry 故障不阻断启动时可关闭。
+
+## 相关文档
+
+- [BFF 运行时框架](/guides/advanced-features/bff/frameworks)
+- [BFF Data Platform](/guides/advanced-features/bff/data-platform)
+- [BFF Effect 运行时配置](/configure/app/bff/effect)
+- [Module Federation SSR](/guides/topic-detail/module-federation/ssr)
+- [performance.rsdoctor](/configure/app/performance/rsdoctor)
+- [server.ssr](/configure/app/server/ssr)

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

@@ -0,0 +1,114 @@
+---
+sidebar_position: 3
+---
+
+import { PackageManagerTabs } from '@theme';
+import ReleaseNote from '@site-docs/components/release-note';
+
+# 版本升级
+
+import Upgrade from '@site-docs/components/auto-upgrade';
+
+<Upgrade />
+
+## 手动升级
+
+Modern.js 所有的官方包使用**统一版本号**进行发布，因此升级时需要将所有 `@modern-js/**` 包的版本统一更新到目标版本。
+
+### 升级步骤
+
+1. **查看最新版本**
+
+   你可以通过以下方式查看 Modern.js 的最新版本：
+
+   - 访问 [npm](https://www.npmjs.com/package/@modern-js/app-tools) 查看 `@modern-js/app-tools` 的最新版本
+   - 查看 [GitHub Releases](https://github.com/web-infra-dev/modern.js/releases)
+
+   <ReleaseNote />
+
+2. **更新 package.json**
+
+   在项目的 `package.json` 中，将所有 `@modern-js/**` 包的版本更新到目标版本。例如：
+
+   ```json title="package.json"
+   {
+     "dependencies": {
+       "@modern-js/app-tools": "3.0.0",
+       "@modern-js/runtime": "3.0.0"
+     },
+     "devDependencies": {
+       "@modern-js/types": "3.0.0"
+     }
+   }
+   ```
+
+3. **重新安装依赖**
+
+   更新完 `package.json` 后，重新安装依赖：
+
+   <PackageManagerTabs command="install" />
+
+:::tip
+当升级时，需要对 Modern.js 官方提供的所有包做统一升级，而不是升级单个依赖。确保所有 `@modern-js/**` 包的版本号保持一致。
+:::
+
+## 版本管理策略
+
+在 Modern.js 项目中，我们推荐所有官方提供的依赖都使用固定版本号，不使用 `^` 或 `~` 进行范围声明。例如：
+
+```json
+{
+  "dependencies": {
+    "@modern-js/app-tools": "x.y.z"
+  }
+}
+```
+
+这样可以确保依赖的版本是完全确定的，从而保证构建的一致性和可预测性。
+
+## 锁定子依赖
+
+当项目某个子依赖出现问题，而 Modern.js 无法立即更新时，可以使用包管理器锁定子依赖版本。
+
+### pnpm
+
+对于使用 pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm install`：
+
+```json title="package.json"
+{
+  "pnpm": {
+    "overrides": {
+      "package-name": "^1.0.0"
+    }
+  }
+}
+```
+
+### Yarn
+
+对于使用 Yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn install`：
+
+```json title="package.json"
+{
+  "resolutions": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+### Npm
+
+对于使用 Npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm install`：
+
+```json title="package.json"
+{
+  "overrides": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+:::info
+对于 Monorepo 仓库，只能在项目根目录的 `package.json` 中锁定依赖版本，并且会影响 Monorepo 中的所有 package。
+
+:::

package/docs/zh/guides/topic-detail/_meta.json

@@ -0,0 +1,8 @@
+[
+  {
+    "type": "dir",
+    "name": "module-federation",
+    "label": "module-federation",
+    "collapsed": true
+  }
+]

package/docs/zh/guides/topic-detail/module-federation/_meta.json

@@ -0,0 +1 @@
+["introduce", "usage", "application", "ssr", "deploy", "i18n"]

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

@@ -0,0 +1,117 @@
+# 应用级别模块
+
+Modern.js 提供了运行时 API，支持快速从应用中导出应用级别的 Module Federation 模块。
+
+我们以 [使用模块联邦](/guides/topic-detail/module-federation/usage) 创建的应用为例，进一步说明如何导入应用级别模块。
+
+## 生产者导出模块
+
+和直接导出组件级别的模块不同，我们需要为应用级别模块创建一个独立的入口来作为 `Module Federation` 的导出。
+
+我们创建 `src/export-App.tsx` 文件：
+
+:::note
+这里可以是任意的文件名，Modern.js 没有做强制约定。
+:::
+
+```ts title="src/export-App.tsx"
+import '@modern-js/runtime/registry/index'; // 这一行必须引入，它会默认导入微前端运行时依赖
+import { render } from '@modern-js/runtime/browser';
+import { createRoot } from '@modern-js/runtime/react';
+import { createBridgeComponent } from '@module-federation/modern-js-v3/react-v19';
+
+const ModernRoot = createRoot();
+export const provider = createBridgeComponent({
+  rootComponent: ModernRoot,
+  render: (Component, dom) =>
+    render(Component as React.ReactElement<{ basename: string }>, dom),
+});
+
+export default provider;
+```
+
+:::note
+请根据你项目中使用的 React 版本来选择对应的导入路径：
+
+- **React 19**：使用 `@module-federation/modern-js-v3/react-v19`
+- **React 18**：使用 `@module-federation/modern-js-v3/react-v18`
+
+你可以通过查看项目的 `package.json` 文件中的 `react` 依赖版本来确定应该使用哪个导入路径。
+:::
+
+该文件会将 `main` 入口的应用根组件传递给 Bridge API，并通过 Bridge 将调用渲染函数将其渲染到指定的节点上。
+
+接下来，我们配置 `module-federation.config.ts`，将导出修改为 `src/export-App.tsx`：
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'remote',
+  manifest: {
+    filePath: 'static',
+  },
+  filename: 'static/remoteEntry.js',
+  exposes: {
+    './app': './src/export-App.tsx',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+:::info
+[`createBridgeComponent`](https://module-federation.io/zh/practice/bridge/react-bridge/export-app.html#createbridgecomponent-api-%E5%8F%82%E8%80%83) 用于导出应用级别模块，Modern.js 相关 API 可以查看 [createRoot](/apis/app/runtime/core/create-root)、[render](/apis/app/runtime/core/render)。
+:::
+
+## 消费者使用模块
+
+然后我们修改消费者配置，移除之前创建的的路由文件 `src/routes/remote/page.tsx`。
+
+我们希望所有访问到 `/remote` 的路由都能被进入上述应用级别模块中，因此我们重新添加 `src/routes/remote/$.tsx`。
+
+:::note
+如果你还不了解 `$.tsx` 的能力，可以阅读 [通配路由](/guides/basic-features/routes/routes#通配路由)。
+:::
+
+```tsx title="src/routes/remote/$.tsx"
+import { createRemoteAppComponent } from '@module-federation/modern-js-v3/react';
+import { loadRemote } from '@module-federation/modern-js-v3/runtime';
+
+const ErrorBoundary = (info?: { error: { message: string } }) => {
+  return (
+    <div>
+      <h2>This is ErrorBoundary Component, Something went wrong:</h2>
+      <pre style={{ color: 'red' }}>{info?.error.message}</pre>
+    </div>
+  );
+};
+const Loading = <div>loading...</div>;
+const RemoteApp = createRemoteAppComponent({
+  loader: () => loadRemote('remote/app'),
+  fallback: ErrorBoundary,
+  loading: Loading,
+});
+
+export default RemoteApp;
+```
+
+:::info
+[`createRemoteAppComponent`](https://module-federation.io/zh/practice/bridge/react-bridge/load-app.html#%E4%BB%80%E4%B9%88%E6%98%AF-createremoteappcomponent) 用于加载应用级别模块。
+:::
+
+## 启动应用
+
+现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `modern dev` 启动两个应用。
+
+启动后，消费者应用访问 `/remote` 路由时，会进入生产者应用中。访问 `http://localhost:8080/remote`，可以看到页面中已经包含了生产者的远程模块的完整页面。
+
+你可以在生产者应用中，创建新的路由文件，并在代码中添加路由导航，可以发现这些功能也能够正常运行。
+
+上述用例可以参考：[Modern.js & Module Federation 应用级别模块](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/app-export)。
+
+## 相关文档
+
+- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)

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

@@ -0,0 +1,104 @@
+# 部署
+
+通常情况下，部署 Module Federation 应用，需要注意两点：
+
+1. 保证消费者配置文件中的远程模块地址无误，消费者能够正确访问到生产者的 `manifest` 文件。
+2. 保证生产者 `manifest` 文件中各个资源能被正确访问到。
+
+我们推荐使用 Modern.js 的 [Node 服务](/guides/basic-features/deploy.html#modernjs-内置-nodejs-服务器)来部署 Module Federation 应用，以获得开箱即用的体验。
+
+## 消费者
+
+对于 Module Federation 的消费者来说，它与生产者的联系就是在配置文件中的远程模块地址。
+
+例如生产者部署在 `https://my-remote-module` 这个域名下，开发者需要修改消费者的配置文件：
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@https://my-remote-module/static/mf-manifest.json',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+此时，消费者将加载远程模块生产环境的 `manifest` 配置文件。
+
+:::note
+上述代码中，远程模块的地址是 `/static/mf-manifest.json`，这只是以 Modern.js 默认的产物路径举例。在实际项目中，开发者需要根据实际的访问路径进行配置。
+:::
+
+## 生产者
+
+对于 Module Federation 的生产者，开发者需要正确的配置 [`output.assetPrefix`](/configure/app/output/asset-prefix) 配置，它会影响到：
+
+1. `mf-manifest.json` 中定义的 `publicPath`，它决定了远程模块其他资源的访问路径。
+2. 通过 Modern.js 服务直接托管产物时，`mf-manifest.json` 文件的访问路径。
+
+在生产环境，开发者需要将 `output.assetPrefix` 配置为生产环境的访问路径。例如我们将生产者部署在 `https://my-remote-module` 这个域名下，需要将 `output.assetPrefix` 配置为 `https://my-remote-module`。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  output: {
+    assetPrefix: 'https://my-remote-module',
+  },
+});
+```
+
+此时，生产者构建产物 `mf-manifest.json` 中定义的 `publicPath` 为 `https://my-remote-module`，例如：
+
+```json
+{
+  "id": "remote",
+  "name": "remote",
+  "metaData": {
+    "name": "remote",
+    "publicPath": "https://my-remote-module/"
+  },
+  "shared": [ /* xxx */ ],
+  "remotes": [],
+  "exposes": [ /* xxx */ ]
+}
+```
+
+消费者在访问远程模块时，会自动将 `publicPath` 拼接在远程模块的资源路径前。
+
+该配置也会影响到生产者 `mf-manifest.json` 的访问路径。例如将这个值设置为 `MyDomain/module-a` 时，`mf-manifest.json` 的托管路径变为 `MyDomain/module-a/static/mf-manifest.json`。
+
+此时，消费者在配置远程模块时，需要配置以下地址：
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@MyDomain/module-a/static/mf-manifest.json',
+  },
+});
+```
+
+## 本地验证部署
+
+Modern.js 提供了 `modern deploy` 命令，可以方便生成可运行在 Node.js 环境的产物。
+
+```bash
+modern deploy
+```
+
+执行命令后，可以在控制台看到以下输出：
+
+```bash
+Static directory: .output/static
+You can preview this build by node .output/index
+```
+
+此时，开发者只需要运行 `node .output/index` 即可在本地预览部署后的效果。无论是 CSR 应用或是 SSR 应用，所有的 Module Federation 产物都能够被正确的访问。