@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.120 → 3.2.0-ultramodern.121

package/docs/zh/community/blog/v2-release-note.mdx

@@ -86,20 +86,20 @@ title: Modern.js v2 发布
 
 大家对 Modern.js 框架的第一印象可能是「一个大而全的框架」，但事实上，为了避免变得臃肿，**Modern.js 采取了渐进式设计**，将所有功能建立在灵活的插件系统之上，因此具备按需启用和可插拔的能力。
 
-Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 ultramodern new 命令一键开启，并自动安装相关依赖。
+Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 modern new 命令一键开启，并自动安装相关依赖。
 
-![ultramodern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
+![modern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
 
-<div style={{ textAlign: 'center', fontStyle: 'italic' }}>ultramodern new 命令</div>
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>modern new 命令</div>
 
 比如：
 
 - 对于基础的开发场景，项目中只需安装 Modern.js 的 CLI 工具 `@modern-js/app-tools`，即具备了开发调试、生产构建的能力。
-- 当你需要在应用中增加一些 BFF 接口时，可以执行 ultramodern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
+- 当你需要在应用中增加一些 BFF 接口时，可以执行 modern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/bff-plugins.png)
 
-目前，你可以通过 `ultramodern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
+目前，你可以通过 `modern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new.png)
 

package/docs/zh/community/blog/v3-release-note.mdx

@@ -338,7 +338,7 @@ export default defineRoutes(({ route, layout, page }) => {
 
 #### 路由调试
 
-运行 `npx ultramodern routes` 命令即可在 `dist/routes-inspect.json` 文件中生成完整的路由结构分析报告。
+运行 `npx modern routes` 命令即可在 `dist/routes-inspect.json` 文件中生成完整的路由结构分析报告。
 
 报告中会显示每个路由的路径、组件文件、数据加载器、错误边界、Loading 组件等完整信息，帮助开发者快速了解项目的路由配置，快速定位和排查路由相关问题。结构化的 JSON 格式也便于 AI agent 理解和分析路由结构，提升 AI 辅助开发的效率。
 

package/docs/zh/community/releases.mdx

@@ -24,8 +24,4 @@ Modern.js 遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 语义化
 
 ## 版本升级
 
-当你需要升级项目中的 Modern.js 版本时，可以使用 `ultramodern upgrade` 命令，参考 [版本升级](/guides/get-started/upgrade)。
-
-```bash
-npx ultramodern upgrade
-```
+Modern.js 3.0 不再提供 `modern upgrade` 命令。需要升级项目时，请按照[版本升级](/guides/get-started/upgrade)中的手动迁移步骤操作。

package/docs/zh/components/build-output.mdx

@@ -3,7 +3,7 @@
 ```bash
 $ pnpm run build
 
-> ultramodern build
+> modern build
 
   Modern.js Framework
 

package/docs/zh/components/debug-app.mdx

@@ -3,7 +3,7 @@
 ```bash
 $ pnpm run dev
 
-> ultramodern dev
+> modern dev
 
   Modern.js Framework
 

package/docs/zh/components/deploy-command.mdx

@@ -1,9 +1,9 @@
-## ultramodern deploy
+## modern deploy
 
-`ultramodern deploy` 命令，用于生成部署平台需要的产物。
+`modern deploy` 命令，用于生成部署平台需要的产物。
 
 ```bash
-Usage: ultramodern deploy [options]
+Usage: modern deploy [options]
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径

package/docs/zh/components/init-app.mdx

@@ -1,4 +1,8 @@
-UltraModern.js 提供 BleedingDev create 包来创建项目，不需要全局安装，直接使用 `pnpm dlx` 按需运行即可。
+UltraModern.js 提供 BleedingDev create 包来创建 SuperApp workspace，不需要全局安装，直接使用 `pnpm dlx` 按需运行即可。
+
+pnpm 支持的命令契约是 scoped package specifier：
+`pnpm dlx @bleedingdev/modern-js-create <target>`。不要简写成
+`pnpm dlx modern-js-create`；npm 上没有这个未加 scope 的包。
 
 你可以在当前已有的空目录中初始化项目：
 
@@ -13,26 +17,6 @@ pnpm dlx @bleedingdev/modern-js-create .
 pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-默认会初始化 TanStack Router。如需强制使用 React Router 兼容路径：
-
-```bash
-pnpm dlx @bleedingdev/modern-js-create myapp --router react-router
-```
-
-默认会初始化 Tailwind CSS v4 模板。如需关闭：
-
-```bash
-pnpm dlx @bleedingdev/modern-js-create myapp --no-tailwind
-```
-
-默认会初始化 Effect HttpApi BFF 模板。
-
-初始化带 Hono 运行时的 BFF 模板：
-
-```bash
-pnpm dlx @bleedingdev/modern-js-create myapp --bff-runtime hono
-```
-
 使用 workspace 协议依赖初始化（用于在本地 monorepo 中联调未发布的 Modern.js 包）：
 
 ```bash
@@ -71,37 +55,22 @@ BleedingDev create 包会直接创建应用，不再提供问答界面：
 
 ```
 .
-├── biome.json
-├── modern.config.ts
+├── apps
+│   └── shell-super-app
 ├── package.json
-├── README.md
-├── src
-│   ├── modern-app-env.d.ts
-│   ├── modern.runtime.ts
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
-└── tsconfig.json
-```
-
-默认会生成 Tailwind CSS v4；传入 `--no-tailwind` 时会省略 `postcss.config.mjs`、`tailwind.config.ts` 和 Tailwind 导入。
-
-默认会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/effect/index.ts` 与 `shared/effect/api.ts`，并将 `bff.runtimeFramework` 设置为 `effect`。
-当启用 `--bff-runtime hono` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/lambda/hello.ts`，并将 `bff.runtimeFramework` 设置为 `hono`。
-当启用 `--workspace` 时，`@modern-js/*` 依赖会使用 `workspace:*` 版本，便于本地 monorepo 联调。
-
-它默认创建一个简单、可上线的 UltraModern 应用，并安装已发布的
-BleedingDev 包别名：
-
-```bash
-pnpm dlx @bleedingdev/modern-js-create myapp
+├── packages
+│   ├── shared-contracts
+│   ├── shared-design-tokens
+│   └── shared-effect-client
+├── scripts
+├── topology
+└── verticals
 ```
 
-只有在需要多个独立归属的 vertical 时，才显式创建 SuperApp workspace：
+默认 workspace 从 shell 起步，并安装已发布的 BleedingDev 包别名：
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
+pnpm dlx @bleedingdev/modern-js-create my-super-app
 ```
 
 在已生成的 SuperApp workspace 根目录中，可以就地添加业务

package/docs/zh/components/serve-command.mdx

@@ -1,9 +1,9 @@
-## ultramodern serve
+## modern serve
 
-`ultramodern serve` 命令用于在生产环境下启动 UltraModern.js 工程, 也可以用于在本地预览生产环境构建的产物。注意你需要提前执行 [`build`](/apis/app/commands#ultramodern-build) 命令构建出对应产物。
+`modern serve` 命令用于在生产环境下启动 UltraModern.js 工程, 也可以用于在本地预览生产环境构建的产物。注意你需要提前执行 [`build`](/apis/app/commands#modern-build) 命令构建出对应产物。
 
 ```bash
-Usage: ultramodern serve [options]
+Usage: modern serve [options]
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径

package/docs/zh/configure/app/bff/effect.mdx

@@ -123,13 +123,35 @@ export default defineConfig({
 }
 ```
 
-- **默认值：** `{ enabled: true }`
+- **默认值：**
+
+```ts
+{
+  enabled: true,
+  requireEnvelope: false,
+  envelopeHeader: 'x-modernjs-data-envelope',
+  validateOrigin: true,
+  requireTraceContext: false,
+  batch: {
+    enabled: true,
+    endpoint: '/_data/batch',
+    maxBatchSize: 16,
+    maxBatchBytes: 64 * 1024,
+    flushIntervalMs: 8,
+    maxConcurrency: 4,
+    requestTimeoutMs: 10000,
+    allowedMethods: ['GET'],
+  },
+}
+```
 
 用于配置 Effect 运行时的数据请求信封（envelope）校验策略。
 
 生成的 Effect 客户端会将批处理请求发送到 `${bff.prefix}${batch.endpoint}`（例如 `/bff-api/_data/batch`）。
 
-当 `validateOrigin` 开启时，运行时会优先将 envelope 中的 origin 与请求 `Origin` 头比对；若请求无 `Origin`，则回退到请求 URL 的 origin。
+Envelope 校验默认开启但不是强制的：未携带 envelope 的请求会继续通过，除非将 `requireEnvelope` 设为 `true`。如果请求携带 envelope，运行时会按配置校验命名空间、origin、trace 与 selection 策略。`expectedNamespace` 默认不设置，`selection` 默认也不限制，除非显式配置。
+
+Origin 校验默认开启。运行时会优先将 envelope 中的 origin 与请求 `Origin` 头比对；若请求无 `Origin`，则回退到请求 URL 的 origin；设置 `validateOrigin: false` 可关闭该比对。
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -150,3 +172,5 @@ export default defineConfig({
 ```
 
 `batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
+
+生成的 `effectBff.client.*` API 只存在于 loader 物化后的 `@api/effect/*` 导入中。直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。

package/docs/zh/configure/app/performance/rsdoctor.mdx

@@ -11,22 +11,23 @@ type RsdoctorConfig =
   | boolean
   | {
       enabled?: boolean;
+      disableClientServer?: boolean;
     };
 ```
 
-- **默认值：** 生产构建时为 `true`，开发模式下为 `false`。
+- **默认值：** `undefined`，未配置该选项时不会启用 Rsdoctor。
 
-用于配置 Modern.js 构建过程中的 Rsdoctor 诊断能力。
+用于配置 Modern.js 构建过程中的 Rsdoctor 诊断能力。将该选项设为 `true` 即可启用 Rsdoctor：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    rsdoctor: false,
+    rsdoctor: true,
   },
 });
 ```
 
-你也可以使用对象形式：
+你也可以使用对象形式。提供对象配置时，除非将 `enabled` 设为 `false`，否则会启用 Rsdoctor：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -37,3 +38,5 @@ export default defineConfig({
   },
 });
 ```
+
+如果需要在共享配置中关闭已经启用的 Rsdoctor，可以将 `rsdoctor` 设为 `false`，或将 `enabled` 设为 `false`。

package/docs/zh/configure/app/usage.mdx

@@ -86,8 +86,8 @@ export default defineConfig(({ env, command }) => ({
 该函数接受以下入参：
 
 - `env`：对应 `process.env.NODE_ENV` 的值。
-  - 当运行 `ultramodern dev` 时，`env` 的值为 `development`。
-  - 当运行 `ultramodern build` 或 `ultramodern serve` 时，`env` 的值为 `production`。
+  - 当运行 `modern dev` 时，`env` 的值为 `development`。
+  - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
 - `command`：对应当前运行的命令，如 `dev`、`build`、`serve`。
 
 #### 导出异步函数
@@ -117,8 +117,8 @@ Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称
 ```json title="package.json"
 {
   "scripts": {
-    "dev": "modern modern",
-    "build": "ultramodern build --config modern.prod.config.ts"
+    "dev": "modern dev",
+    "build": "modern build --config modern.prod.config.ts"
   }
 }
 ```
@@ -126,7 +126,7 @@ Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称
 你也可以将 `--config` 选项缩写为 `-c`：
 
 ```bash
-$ ultramodern build -c modern.prod.config.js
+$ modern build -c modern.prod.config.js
 ```
 
 ### 在 package.json 中配置（不推荐）
@@ -187,7 +187,7 @@ export default defineConfig({
 
 在使用 `modern.config.local.ts` 时，请注意以下事项：
 
-- `modern.config.local.ts` 文件仅会在执行 `ultramodern dev` 命令时被加载，当执行 `ultramodern build` 时不会被加载。
+- `modern.config.local.ts` 文件仅会在执行 `modern dev` 命令时被加载，当执行 `modern build` 时不会被加载。
 - `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
 - 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
 

package/docs/zh/guides/advanced-features/bff/data-platform.mdx

@@ -55,12 +55,14 @@ export default defineConfig({
 });
 ```
 
-当启用 `validateOrigin` 时，Effect 运行时会优先使用请求中的 `Origin` 头进行 origin 校验；若不存在 `Origin`，则回退到请求 URL 的 origin。
+Envelope 校验默认开启，但只有设置 `requireEnvelope` 时才强制要求请求携带 envelope。Origin 校验默认开启；设置 `validateOrigin: false` 后，运行时不会再将 envelope 中的 origin 与请求 `Origin` 头比对，也不会在缺少该请求头时回退到请求 URL 的 origin。
 
 ## Effect 客户端自动行为
 
 使用生成的 Effect 客户端（`@api/effect/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
 
+生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/effect/*` 导入；直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
+
 Envelope 默认包含：
 
 - operation 元数据

package/docs/zh/guides/advanced-features/bff/frameworks.mdx

@@ -105,7 +105,7 @@ const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
 export default defineEffectBff({ api: bffEffectApi, layer });
 ```
 
-在浏览器端通过 `@api/effect/index` 调用接口：
+在浏览器代码中通过 `@api/effect/index` 调用接口：
 
 ```ts title="src/routes/page.tsx"
 import effectBff from '@api/effect/index';
@@ -113,6 +113,8 @@ import effectBff from '@api/effect/index';
 const response = await effectBff.client.hello.ping({});
 ```
 
+`effectBff.client.*` 由 BFF loader 针对 `@api/effect/*` 导入物化生成。不要直接导入 `api/effect/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+
 import Hono from '@site-docs/components/hono';
 
 <Hono />

package/docs/zh/guides/advanced-features/international/api.mdx

@@ -20,7 +20,7 @@ title: API 参考
 | `isResourcesReady` | `boolean` | 当前语言的翻译资源是否已加载完成 |
 | `i18nInstance` | `I18nInstance` | i18next 实例（用于高级场景） |
 
-启用 `localePathRedirect` 且省略 `localisedUrls` 时，Modern.js 会将本地化 URL 路径视为已启用。除非设置 `localisedUrls: false`，否则路由生成仍要求每个可本地化路径都为所有已配置语言提供路径。
+启用 `localePathRedirect` 且省略 `localisedUrls` 时，Modern.js 会保持 `/en/about` 这类仅语言前缀路径。只有提供非空 `localisedUrls` 映射时，才会启用路径片段翻译。也只有在该映射启用时，路由生成才会校验每个可本地化路径是否覆盖所有已配置语言。
 
 ### 基本用法
 

package/docs/zh/guides/advanced-features/international/configuration.mdx

@@ -48,7 +48,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | 支持的语言列表 |
 | `fallbackLanguage` | `string` | `''` | 语言检测失败时的兜底语言 |
 | `localePathRedirect` | `boolean` | `false` | 接管 URL 语言前缀的识别、重定向和切换，详见[路由集成](./routing.md#启用语言路径前缀) |
-| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 启用 `localePathRedirect` 时为 `true` | 本地化路由路径映射。每个可本地化路由都必须为所有已配置语言提供路径。设置为 `false` 时只保留语言前缀，不翻译路径片段。 |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 仅语言前缀行为 | 本地化路由路径映射。只有非空映射会启用路径片段翻译；省略、`true`、`false` 和 `{}` 都会保留语言前缀但不翻译路径片段。 |
 | `i18nextDetector` | `boolean` | `false` | 启用 i18next 检测器（Cookie / Header 等） |
 | `detection` | `LanguageDetectorOptions` | — | i18next 检测器详细配置，见[语言检测](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | — | 跳过重定向的路由，见[语言检测](./locale-detection.md#ignoreredirectroutes) |

package/docs/zh/guides/advanced-features/international/locale-detection.mdx

@@ -113,7 +113,7 @@ i18nPlugin({
 
 ## ignoreRedirectRoutes
 
-指定哪些额外路径跳过语言路径重定向。Modern.js 会自动跳过服务端 API 路由和 BFF 前缀，包括配置的 `bff.prefix`。`ignoreRedirectRoutes` 适用于其他不需要语言前缀的非 API 业务路径。
+指定哪些额外路径跳过语言路径重定向。Modern.js 会自动跳过服务端 API 路由、启用 BFF 但未配置前缀时的默认 `/api` 前缀，以及自定义 `bff.prefix`。`ignoreRedirectRoutes` 适用于其他不需要语言前缀的非 API 业务路径。
 
 **写法一：字符串数组**（支持精确匹配和前缀匹配）
 

package/docs/zh/guides/advanced-features/international/routing.mdx

@@ -32,11 +32,13 @@ i18nPlugin({
 | `/en/about` | 正常访问，语言为 `en` |
 | `/zh/about` | 正常访问，语言为 `zh` |
 
-API 和 BFF 前缀会自动跳过，因此服务端 API 路由不需要语言前缀，也不需要配置 `localisedUrls`。如果还有其他业务路径不应该重定向，可以使用 `ignoreRedirectRoutes`，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
+API 和 BFF 前缀会自动跳过，包括服务端 API 路由、启用 BFF 但未配置前缀时的默认 `/api` 前缀，以及自定义 `bff.prefix`。这些路由不需要语言前缀，也不需要配置 `localisedUrls`。如果还有其他业务路径不应该重定向，可以使用 `ignoreRedirectRoutes`，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
 
 ## 本地化 URL 路径
 
-启用 `localePathRedirect` 后，`localisedUrls` 默认启用。每个可本地化的路由路径都必须为所有已配置语言提供 URL。如果向 `languages` 中新增语言，Modern.js 会在路由生成阶段失败，直到每个 `localisedUrls` 条目都补齐该语言。
+默认情况下，`localePathRedirect` 只会添加和识别语言前缀，例如 `/en/about`。翻译路径片段需要显式开启：只有提供非空 `localisedUrls` 映射时才会启用。省略 `localisedUrls`、设置为 `true`、设置为 `false` 或传入空对象时，都会保持仅语言前缀的行为。
+
+配置非空 `localisedUrls` 映射后，每个可本地化的路由路径都必须为所有已配置语言提供 URL。如果向 `languages` 中新增语言，Modern.js 会在路由生成阶段失败，直到每个 `localisedUrls` 条目都补齐该语言。
 
 `localisedUrls` 同时适用于 React Router 和 TanStack Router 项目的约定式路由。不要为 API 路由、BFF 前缀或配置的 `bff.prefix` 添加本地化 URL 条目；这些路径会自动排除在语言重定向之外。
 
@@ -73,7 +75,7 @@ i18nPlugin({
 | `/cs/terms-of-service` | 重定向到 `/cs/podminky-pouzivani` |
 | `/cs/podminky-pouzivani` | 正常访问，语言为 `cs` |
 
-只有在希望保留语言前缀、但不翻译路径片段时，才设置 `localisedUrls: false`。
+当 preset、共享配置或生成的元数据本来会提供映射，但当前入口只希望保留语言前缀、不翻译路径片段时，可以设置 `localisedUrls: false` 作为逃生口。
 
 ## 路由配置
 

package/docs/zh/guides/basic-features/debug/rsdoctor.mdx

@@ -2,14 +2,13 @@
 
 Rsdoctor 是一个 Rspack 构建分析工具。在 Modern.js 中，我们推荐使用 Rsdoctor 来对构建过程与构建产物进行诊断和分析。
 
-Modern.js 默认会在生产构建中开启 Rsdoctor。
+Modern.js 不会默认启用 Rsdoctor。当你需要在构建中运行 Rsdoctor 时，请配置 `performance.rsdoctor`。
 
 ## 执行构建
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    // 在 production build 默认启用
     rsdoctor: true,
   },
 });
@@ -21,7 +20,7 @@ npm run build
 
 ## 关闭 Rsdoctor
 
-如果你希望关闭 Rsdoctor：
+如果你希望在共享配置中关闭已经启用的 Rsdoctor：
 
 ```ts title="modern.config.ts"
 export default defineConfig({

package/docs/zh/guides/basic-features/debug/using-storybook.mdx

@@ -54,7 +54,7 @@ export default config
 ```json
 {
   "scripts": {
-    "dev:api": "ultramodern dev --api-only",
+    "dev:api": "modern dev --api-only",
     "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
   }
 }

package/docs/zh/guides/basic-features/deploy.mdx

@@ -15,11 +15,11 @@ sidebar_position: 15
 
 ## 构建部署产物
 
-执行 `ultramodern deploy` 命令将自动输出部署产物。此过程包括优化 Bundler 构建产物及产物依赖，检测当前部署平台，并自动生成可以在该平台运行的产物。
+执行 `modern deploy` 命令将自动输出部署产物。此过程包括优化 Bundler 构建产物及产物依赖，检测当前部署平台，并自动生成可以在该平台运行的产物。
 如果你希望在本地生成并测试特定部署平台的产物，可以通过设置环境变量来指定平台：
 
 ```bash
-MODERNJS_DEPLOY=netlify npx ultramodern deploy
+MODERNJS_DEPLOY=netlify npx modern deploy
 ```
 
 :::info
@@ -35,10 +35,10 @@ MODERNJS_DEPLOY=netlify npx ultramodern deploy
 你可以使用以下命令构建项目：
 
 ```bash
-npx ultramodern deploy
+npx modern deploy
 ```
 
-当执行 `ultramodern deploy` 命令时，UltraModern.js 将生成可执行的部署产物，并在控制台输出以下内容：
+当执行 `modern deploy` 命令时，UltraModern.js 将生成可执行的部署产物，并在控制台输出以下内容：
 
 ```bash
 Static directory: `.output/static`
@@ -66,7 +66,7 @@ PORT=3000 node .output/index
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && ultramodern deploy"
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -77,7 +77,7 @@ PORT=3000 node .output/index
 {
   "scripts": {
     "build:packages": "rush rebuild --to-except app",
-    "deploy": "rushx build:packages && ultramodern deploy"
+    "deploy": "rushx build:packages && modern deploy"
   }
 }
 ```
@@ -105,7 +105,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 ```toml
 [build]
   publish = "dist"
-  command = "ultramodern deploy"
+  command = "modern deploy"
 ```
 
 :::info
@@ -121,7 +121,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 ```toml title="netlify.toml"
 [build]
   publish = "dist"
-  command = "ultramodern deploy"
+  command = "modern deploy"
 
 [functions]
   directory = ".netlify/functions"
@@ -167,7 +167,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && ultramodern deploy"
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -207,7 +207,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 
 ```json title="vercel.json"
 {
-  "buildCommand": "ultramodern deploy",
+  "buildCommand": "modern deploy",
   "outputDirectory": ".vercel/output"
 }
 ```
@@ -272,7 +272,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && ultramodern deploy"
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -311,12 +311,12 @@ Github Pages 支持两种部署方式，通过分支部署或通过 Github Actio
 
 1. 在 github 仓库中，选择 `Settings > Pages > Source > Deploy from a branch`。
 2. 安装 `gh-pages` 依赖作为开发依赖。
-3. 在 package.json 的 `scripts` 中添加 `"deploy:gh-pages": "MODERNJS_DEPLOY=ghPages ultramodern deploy && gh-pages -d .output"`。
+3. 在 package.json 的 `scripts` 中添加 `"deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"`。
 4. 执行 `npm run deploy:gh-pages`。
 
 :::info
 
-1. 执行 `MODERNJS_DEPLOY=ghPages ultramodern deploy`，UltraModern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
+1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，UltraModern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
 2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
 
 :::

package/docs/zh/guides/basic-features/env-vars.mdx

@@ -16,8 +16,8 @@ Modern.js 提供了对环境变量的支持，包含内置的环境变量和自
 
 表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
 
-- `production`：执行 `ultramodern build`、`ultramodern serve` 命令时的默认值。
-- `development`：执行 `ultramodern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
+- `production`：执行 `modern build`、`modern serve` 命令时的默认值。
+- `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
 
 ### MODERN_ENV
 

package/docs/zh/guides/basic-features/render/_meta.json

@@ -1,10 +1 @@
-[
-  "overview",
-  "ssr",
-  "streaming-ssr",
-  "ssr-cache",
-  "ssg",
-  "rsc",
-  "tanstack-rsc",
-  "before-render"
-]
+["overview", "ssr", "streaming-ssr", "ssr-cache", "ssg", "rsc", "before-render"]

package/docs/zh/guides/basic-features/render/overview.mdx

@@ -48,6 +48,5 @@ Modern.js 支持多种渲染模式组合使用：
 - [服务端渲染（SSR）](/guides/basic-features/render/ssr)
 - [流式服务端渲染（Streaming SSR）](/guides/basic-features/render/streaming-ssr)
 - [React Server Components（RSC）](/guides/basic-features/render/rsc)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)
 - [静态站点生成（SSG）](/guides/basic-features/render/ssg)
 - [渲染缓存](/guides/basic-features/render/ssr-cache)

package/docs/zh/guides/basic-features/render/rsc.mdx

@@ -616,4 +616,3 @@ import DeployTip from '@site-docs/components/rsc-deploy-tip';
 - [数据缓存](/guides/basic-features/data/data-cache)
 - [服务端渲染（SSR）](/guides/basic-features/render/ssr)
 - [Streaming SSR](/guides/basic-features/render/streaming-ssr)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)

package/docs/zh/guides/basic-features/routes/config-routes.mdx

@@ -270,7 +270,7 @@ Modern.js 会自动查找并加载：
 
 :::info
 
-当前路由结构可以通过 [`ultramodern routes`](#调试路由) 命令查看
+当前路由结构可以通过 [`modern routes`](#调试路由) 命令查看
 
 :::
 
@@ -318,7 +318,7 @@ export default defineRoutes(({ page }, fileRoutes) => {
 
 ```bash
 # 生成路由结构分析报告
-npx ultramodern routes
+npx modern routes
 ```
 
 该命令会在 `dist/routes-inspect.json` 文件中生成最终的路由结构，帮助你了解合并后的完整路由信息。

package/docs/zh/guides/basic-features/routes/routes.mdx

@@ -476,27 +476,27 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 
 :::tip
 
-路由数据预热需要显式开启。在 SSR 项目中，只有匹配到的路由通过 `handle.navigationWarmup.data` 开启后，才会预取 [Data Loader](/guides/basic-features/data/data-fetch) 返回的数据。
+在 SSR 项目中，同源路由会为匹配到且带有可调用 loader 的路由预取 [Data Loader](/guides/basic-features/data/data-fetch) 返回的数据。如果某个路由的 loader 数据不应该在导航前请求，可以将该路由的 `handle.navigationWarmup.data` 设置为 `false`。
 
 :::
 
-默认情况下，同源链接会在 `<Link>` 渲染时预取路由模块，并在链接进入视窗时进行预加载。当用户开启 Save-Data 或处于慢速网络时，Modern.js 会跳过这些自动预热。
+默认情况下，同源链接会在 `<Link>` 渲染时预取路由模块和匹配到的 loader 数据。当用户开启 Save-Data 或处于慢速网络时，Modern.js 会跳过这些自动预热。
 
 `prefetch` 属性有四个可选值：
 
 - `render`，默认值。当 `<Link>` 组件渲染时，就会预热对应的路由模块。
 - `intent`，当用户聚焦、悬停或触摸链接时，会开始预热对应的路由模块。如果意图在预热开始前取消，预热也会取消。
 - `viewport`，当 `<Link>` 组件进入视窗时，会开始预热对应的路由模块。
-- `none`，关闭自动 render prefetch。如果没有显式设置 `preload`，也会关闭默认的 viewport preload。
+- `none`，关闭自动 prefetch。如果没有显式设置 `preload`，也会关闭隐式 preload。
 
-`preload` 属性接受同样的时机值，默认值为 `viewport`。显式设置的 `preload` 总是优先生效，`preload={false}` 会关闭 preload 行为。
+`preload` 属性接受同样的时机值，默认跟随 `prefetch` 的时机。显式设置的 `preload` 总是优先生效，`preload={false}` 会关闭 preload 行为。
 
-如果要让某个路由开启 SSR 数据预热：
+如果要让某个路由关闭 SSR 数据预热：
 
 ```ts title="routes/page.config.ts"
 export const handle = {
   navigationWarmup: {
-    data: true,
+    data: false,
   },
 };
 ```
@@ -505,7 +505,7 @@ export const handle = {
 
 - `render` 可以通过 `<Link>` 组件在组件树中的位置控制路由模块预热时机。
 - `viewport` 可以把模块预热推迟到链接接近可操作时再触发。
-- SSR 数据预取默认不开启；只有当路由的 loader 数据适合在导航前获取时，才应该使用 `handle.navigationWarmup.data`。
+- SSR 数据预取默认开启；当路由的 loader 数据不适合在导航前获取时，使用 `handle.navigationWarmup.data = false` 关闭。
 
 :::