@modern-js/main-doc 2.66.0 → 2.66.1-alpha.1

package/docs/zh/configure/app/runtime/0-intro.mdx

@@ -1,120 +1,105 @@
----
-title: 总览
-sidebar_position: 1
----
+# 介绍
 
-# 总览
+Modern.js 的运行时（Runtime）配置需集中在 `src/modern.runtime.ts` 文件中声明。
 
-此节将介绍 Runtime 插件的配置。
-
-## 配置方式
-
-### runtime
-
-- **类型：** `Object`
+:::info
+如果项目中还没有此文件，请执行以下命令创建：
 
-runtime 配置方式如下：
+```bash
+touch src/modern.runtime.ts
+```
 
-#### 基本用法
+:::
 
-在 `modern.config.ts` 中配置
+## 基本配置
 
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-export default defineConfig({
-  runtime: {
-    state: true,
-    router: true,
+export default defineRuntimeConfig({
+  router: {
+    // 路由配置
+  },
+  state: {
+    // 状态管理配置
   },
+  // 其他运行时模块...
 });
 ```
 
-#### 运行时配置
+## 多入口配置
 
-通过 [`defineConfig`](/apis/app/runtime/app/define-config) API 配置：
+对于多入口应用，`defineRuntimeConfig` 函数可以根据入口名称返回特定的配置：
 
-:::info
-当 runtime 配置中存在函数时，只能使用该方式进行配置。
-
-:::
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-import { Tabs, Tab as TabItem } from "@theme";
-
-<Tabs>
-  <TabItem value="layout" label="约定式路由" default>
-
-```tsx title="src/routes/layout.tsx"
-import type { AppConfig } from '@modern-js/runtime';
-
-export const config = (): AppConfig => {
-  return {
-    router: {
-      supportHtml5History: false
-    }
+export default defineRuntimeConfig(entryName => {
+  if (entryName === 'main') {
+    return {
+      router: {
+        // "main" 入口的路由配置
+      },
+      state: {
+        // "main" 入口的状态管理配置
+      },
+    };
   }
-};
-```
-
-  </TabItem>
-
-  <TabItem value="app" label="自控路由">
-
-```ts title="src/App.tsx"
-import { defineConfig } from '@modern-js/runtime';
-
-const App = () => {
-  /** */
-};
 
-defineConfig(App, {
-  router: {
-    supportHtml5History: false,
-  },
+  // 其他入口的配置
+  return {
+    masterApp: {
+      // 微前端配置示例
+    },
+  };
 });
-
-export default App;
 ```
 
-  </TabItem>
-</Tabs>
-
-:::info
-使用运行时配置，可以解决 Runtime 插件配置需要在运行时才能获取到具体内容问题。
-
-Runtime 插件运行时配置和直接在 `modern.config.ts` 中的配置默认会进行合并，且运行时配置优先级更高。
-
+:::tip
+使用 `src/modern.runtime.ts` 配置方式不支持导出异步函数，这与 Modern.js 的渲染方式有关。如果需要添加异步逻辑，请使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)**。
 :::
 
 :::warning
-defineConfig 中只能定义 Runtime 插件的具体配置内容，确认是否开启插件还需要通过 `modern.config.ts` 中的配置决定。
-
+使用 `src/modern.runtime.ts` 配置方式需要 Modern.js 版本 **MAJOR_VERSION.66.0** 或更高版本。
 :::
 
-### runtimeByEntries
+import RuntimeCliConfig from '@site-docs/components/runtime-cli-config';
+
+<RuntimeCliConfig />
 
-- **类型：** `Object`
-- **默认值：**无
+## 配置方式演进
 
-#### 说明
+在 MAJOR_VERSION.66.0 之前，运行时配置分散在多个位置：
 
-按入口添加 runtime 配置，选项属性同 runtime 一致，指定值会和 runtime 属性内容做替换合并操作。
+1. `modern.config.ts` 中的 `runtime` 和 `runtimeByEntries` 字段
+2. 各入口的 `App.config` 或 `layout` 文件导出的 `config` 函数
 
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
+为提升可维护性，Modern.js 引入了统一的 `src/modern.runtime.ts` 配置入口。
 
-export default defineConfig({
+### 旧配置方式（兼容但不推荐）
+
+```ts
+// modern.config.ts
+export default {
   runtime: {
-    state: false,
+    /* ... */
   },
   runtimeByEntries: {
-    entry1: {
-      state: true, // { state: true }
-    },
-    entry2: {
-      // { state: false, router: true }
-      router: true,
-    },
+    /* ... */
   },
-});
+};
+
+// App.config
+App.config = {
+  /* ... */
+};
+
+// layout 文件
+export const config = () => {
+  /* 动态配置逻辑 */
+};
 ```
+
+### 迁移建议
+
+强烈建议将所有运行时配置迁移至 `src/modern.runtime.ts`。虽然旧配置方式目前仍兼容，但计划在未来版本中逐步废弃。统一配置入口可避免配置分散，显著提高项目可维护性。

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

@@ -1,12 +1,8 @@
----
-sidebar_position: 0
----
-
 # 配置使用
 
-Modern.js 中有两种配置，分别是编译时配置和服务端运行时配置。
+Modern.js 中有三种配置，分别是编译时配置、运行时配置和服务端运行时配置。
 
-编译时配置可以在两个位置进行配置：
+**编译时配置**可以在两个位置进行配置：
 
 - 根路径下的 `modern.config.(ts|js|mjs)` 文件
 - `package.json` 文件
@@ -15,9 +11,14 @@ Modern.js 中有两种配置，分别是编译时配置和服务端运行时配
 Modern.js 不支持同时在 `package.json` 中和 `modern.config.ts` 中配置同一个配置项，推荐在 `modern.config.ts` 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
 :::
 
-服务端运行时配置可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中进行配置。
+**运行时配置**可以在 `src/modern.runtime.(ts|js|mjs)` 文件中配置。
+
+{/* TODO server 配置文件更新 */}
+**服务端运行时配置**可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中进行配置。
 
-## 在配置文件中配置
+## 编译时配置
+
+### 在配置文件中配置
 
 Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js` 和 `.mjs` 格式：
 
@@ -25,7 +26,7 @@ Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js`
 - `modern.config.js`
 - `modern.config.mjs`
 
-### modern.config.ts（推荐）
+#### modern.config.ts（推荐）
 
 我们推荐使用 `.ts` 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
 
@@ -52,7 +53,7 @@ export default defineConfig({
 });
 ```
 
-### modern.config.js
+#### modern.config.js
 
 如果你在开发一个非 TypeScript 项目，可以使用 `.js` 格式的配置文件：
 
@@ -76,7 +77,7 @@ export default {
 };
 ```
 
-### 导出配置函数
+#### 导出配置函数
 
 Modern.js 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Modern.js。
 
@@ -99,7 +100,7 @@ export default defineConfig(({ env, command }) => ({
   - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
 - `command`：对应当前运行的命令，如 `dev`、`start`、`build`、`serve`。
 
-### 导出异步函数
+#### 导出异步函数
 
 Modern.js 也支持在配置文件中导出一个异步函数，你可以在函数中进行一些异步操作：
 
@@ -117,7 +118,7 @@ export default defineConfig(async ({ env, command }) => {
 });
 ```
 
-### 指定配置文件
+#### 指定配置文件
 
 Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称。
 
@@ -138,7 +139,7 @@ Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称
 $ modern build -c modern.prod.config.js
 ```
 
-## 在 package.json 中配置（不推荐）
+### 在 package.json 中配置（不推荐）
 
 除了配置文件外，你也可以在 `package.json` 中的 `modernConfig` 字段下设置配置项，如：
 
@@ -156,16 +157,16 @@ $ modern build -c modern.prod.config.js
 
 由于 JSON 文件格式的限制，`package.json` 中只能定义数字、字符串、布尔值、数组等简单类型的值，当我们需要设置函数类型的值时，建议在 Modern.js 配置文件中进行设置。
 
-### 注意事项
+#### 注意事项
 
 - 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示错误。
 - `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。
 
-## 本地调试配置
+### 本地调试配置
 
 为了便于本地调试配置，Modern.js 支持在项目根目录下创建 `modern.config.local.(ts|js|mjs)` 文件，用于覆盖 `modern.config.(ts|js|mjs)` 中的配置选项。
 
-### 示例
+#### 示例
 
 比如，项目的 `modern.config.ts` 中配置了端口号为 `3000`:
 
@@ -193,7 +194,7 @@ export default defineConfig({
 
 `modern.config.local.ts` 文件中的配置会与 `modern.config.ts` 中的配置进行深层合并，并覆盖 `modern.config.ts` 中的配置选项，因此 `server.port` 会被覆盖为 `3001`。
 
-### 注意事项
+#### 注意事项
 
 在使用 `modern.config.local.ts` 时，请注意以下事项：
 
@@ -205,13 +206,13 @@ export default defineConfig({
 modern.config.local.*
 ```
 
-## 合并多份配置
+### 合并多份配置
 
 在某些情况下，你可能需要将多份配置合并为一份配置，此时你可以使用 `mergeConfig` 工具函数来合并多个配置。
 
 `mergeConfig` 函数接受一个数组作为参数，数组中的每一项都是一个配置对象，`mergeConfig` 会将数组中的每一项配置对象进行深层合并，自动将多个函数项合并为数组，最终返回一个合并后的配置对象。
 
-### 示例
+#### 示例
 
 ```ts title="modern.config.ts"
 import { mergeConfig } from '@modern-js/app-tools';
@@ -249,7 +250,7 @@ const mergedConfig = {
 };
 ```
 
-## 配置类型定义
+### 配置类型定义
 
 Modern.js 导出了 `AppUserConfig` 类型，对应 Modern.js 配置对象的类型：
 
@@ -274,3 +275,25 @@ const config: AppUserConfig<'rspack'> = {
   },
 };
 ```
+
+## 运行时配置
+
+运行时配置的详细信息可以参考 [Runtime 配置介绍](/configure/app/runtime/0-intro.html)。
+
+:::tip
+如果当前的 Runtime 配置需要在编译时和运行时同时使用，请将相关配置参数添加到插件注册的位置。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { statePlugin } from '@modern-js/plugin-state';
+
+export default defineConfig({
+  plugins: [
+    statePlugin({
+      /** 在此处添加参数 */
+    }),
+  ],
+});
+```
+
+:::

package/docs/zh/guides/advanced-features/web-server.mdx

@@ -4,25 +4,17 @@ sidebar_position: 16
 
 # 自定义 Web Server
 
-Modern.js 作为以客户端为中心的开发框架，对服务端的定制能力较弱。而在有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等。
+Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
 
-一些开发者可能会有疑惑，Modern.js 已经提供了 [BFF 能力](/guides/advanced-features/bff/function.html)，为什么还需要**自定义 Web Server**。
+Modern.js 提供了 **渲染中间件（Middleware）** 与**生命周期钩子（Hook）** 两类 API 来扩展 Web Server。
 
-因为在默认情况下，页面路由并不会经过 BFF，它没有办法为页面访问提供服务端的定制逻辑。之所以这样设计，是因为我们不希望控制页面的服务与 BFF 服务绑定在一起，避免 BFF 的框架限制页面的部署方式。例如将页面与 BFF 分开托管、将页面服务部署到非 Node 的环境上，或是针对部署平台做定制等。
-
-出于上述原因，Modern.js 提供了三种方式，让项目可以在根据需求，渐进式的定制服务端能力。
-
-:::warning
-三种扩展方式无法同时工作，开发者需要根据场景选择合适的方式。
+:::note
+Middleware 与 Hook 只会在用户请求页面路由时生效，BFF 路由不会经过这些 API。
 :::
 
-## 使用 API 扩展 Web Server
-
-第一种方式是通过 Modern.js 提供的服务端运行时 API，在特定的生命周期对服务端进行定制。提供这种方式的目的是在部分情况下，开发者并不需要控制完整的 Web Server，只需要添加服务端逻辑即可。
+## 开启自定义 Web Server
 
-这种方式无法控制完整的 Web Server，并且扩展逻辑**只在请求页面时生效**。因此，它适用于服务端逻辑相对简单，不希望额外创建 BFF 或者 BFF 和页面无需公用服务端逻辑场景。
-
-可以在项目根目录执行 `pnpm run new` 命令，开启「自定义 Web Serve」功能：
+开发者可以在项目根目录执行 `pnpm run new` 命令，开启「自定义 Web Server」功能：
 
 ```bash
 ? 请选择你想要的操作 创建工程元素
@@ -39,78 +31,13 @@ export default defineConfig({
 });
 ```
 
-开启功能后，项目目录下会自动创建 `server/index.ts` 文件，可以在这个文件中编写自定义逻辑。Modern.js 提供了 **Hook** 与 **Middleware** 两类 API 来扩展 Web Server。
-
-### Hook
-
-Modern.js 提供的 Hook 用于控制 Web Server 中的内置逻辑，所有的页面请求都会经过 Hook。
-
-目前提供了两种 Hook，分别是 `AfterMatch` 和 `AfterRender`，可以用于修改渲染结果。可以在 `server/index.ts` 中这样写：
+开启功能后，项目目录下会自动创建 `server/index.ts` 文件，可以在这个文件中编写自定义逻辑。
 
-```ts
-import type {
-  AfterMatchHook,
-  AfterRenderHook,
-} from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatchHook = (ctx, next) => {
-  next();
-};
-
-export const afterRender: AfterRenderHook = (ctx, next) => {
-  next();
-};
-```
-
-项目在使用 Hook 时，应该有以下最佳实践：
-
-1. 在 afterMatch 中做权限校验。
-2. 在 afterMatch 做 Rewrite 和 Redirect。
-3. 在 afterRender 中做 HTML 内容注入。
-
-:::note
-详细 API 和更多用法可以查看 [Hook](/apis/app/runtime/web-server/hook)。
-:::
-
-### Middleware
-
-对于某些项目，可能在服务端有更多的需求，Modern.js 提供了 Middleware 为 Web Server 添加前置中间件。它只能运行在 Node 环境下，因此如果项目被部署到其他环境中，如 Worker 环境，则不可以使用 Middleware。
-
-:::note
-下一个大版本，Modern.js 将会使用新 Middleware 来替代该写法。
-
-推荐使用 [UnstableMiddleware](/guides/advanced-features/web-server.html#unstablemiddleware) 处理页面请求。
-:::
-
-Modern.js 默认提供了一套 API 供项目使用：
-
-```ts
-import { Middleware } from '@modern-js/runtime/server';
-
-export const middleware: Middleware = (context, next) => {
-  const {
-    source: { req, res },
-  } = context;
-  console.log(req.url);
-  next();
-};
-```
-
-:::note
-详细 API 和更多用法可以查看 [Middleware](/apis/app/runtime/web-server/middleware)。
-:::
-
-项目在使用 Middleware 时，应该有以下最佳实践：
-
-1. 在 Middleware 中可以直接操作原生的请求、响应对象，做数据打点、注入 SSR 渲染可能用到的 Node 服务（数据库、Redis 等）。
-2. 在 Middleware 里可以做类似功能打标、爬虫优化等功能。
-3. 在 Middleware 里可以无视后续默认渲染，自定义渲染流程。
-
-**总的来说，CSR 项目中，使用 Hook 基本能满足简单场景的所有需求。SSR 项目中，可以使用 Middleware 做更复杂的 Node 扩展。**
+## 自定义 Web Server 能力
 
 ### Unstable Middleware
 
-Modern.js 将提供新 Middleware 为 Web Server 添加前置中间件，支持在处理页面的前后执行自定义逻辑。
+Modern.js 支持为 Web Server 添加渲染中间件，支持在处理页面路由的前后执行自定义逻辑。
 
 ```ts title="server/index.ts"
 import {
@@ -131,30 +58,41 @@ const time: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
 export const unstableMiddleware: UnstableMiddleware[] = [time];
 ```
 
-:::note
-详细 API 和更多用法查看 [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware)
+:::info
+详细 API 和更多用法查看 [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware)。
 :::
 
-## 通过 BFF 托管页面请求
+### Hook
 
-第二种方式，是利用 BFF 来托管页面渲染，这种方式下，所有的请求都会先打到 BFF 的服务。
+:::warning
+我们推荐使用 UnstableMiddleware 代替 Hook。
+:::
 
-因为这种方式可以通过 BFF 统一控制所有请求的服务端逻辑。因此，它适用于服务端逻辑复杂，BFF 和页面需要公用服务端逻辑的场景。但它整体还是依托于 Modern.js 的 Web Server 运行，无法将逻辑运行在已有的服务上。
+Modern.js 提供的 Hook 用于控制 Web Server 中的特定逻辑，所有的页面请求都会经过 Hook。
 
-使用这种方式，我们需要先通过 `pnpm new` 开启「BFF」功能。然后在配置文件中添加 [`bff.enableHandleWeb`](/configure/app/bff/enable-handle-web.html) 配置：
+目前提供了两种 Hook，分别是 `AfterMatch` 和 `AfterRender`，开发者可以在 `server/index.ts` 中这样写：
 
 ```ts
-export default defineConfig({
-  bff: {
-    enableHandleWeb: true,
-  },
-});
+import type {
+  AfterMatchHook,
+  AfterRenderHook,
+} from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatchHook = (ctx, next) => {
+  next();
+};
+
+export const afterRender: AfterRenderHook = (ctx, next) => {
+  next();
+};
 ```
 
-当该值设置为 `true` 时，页面请求流量也会经过 BFF，并且 Modern.js 内置的页面渲染的逻辑默认会作为 BFF 服务的最后一个中间件运行。
+项目在使用 Hook 时，应该有以下最佳实践：
 
-## 完全自定义的 Web Server
+1. 在 afterMatch 中做权限校验。
+2. 在 afterMatch 做 Rewrite 和 Redirect。
+3. 在 afterRender 中做 HTML 内容注入。
 
-:::note
-敬请期待
+:::info
+详细 API 和更多用法可以查看 [Hook](/apis/app/runtime/web-server/hook)。
 :::

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

@@ -1 +1 @@
-["ssr", "streaming-ssr", "ssr-cache", "ssg"]
+["ssr", "streaming-ssr", "ssr-cache", "ssg", "before-render"]

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

@@ -0,0 +1,115 @@
+# 渲染预处理 (Render Preprocessing)
+
+在某些场景下，应用需要在渲染前执行预处理操作。Modern.js 推荐使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)** 来实现这类逻辑。
+
+## 定义 Runtime 插件
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const myRuntimePlugin = (): RuntimePluginFuture => ({
+  name: 'my-runtime-plugin',
+  setup: (api) => {
+    api.onBeforeRender((context) => {
+      // 在渲染前执行的逻辑
+      console.log('Before rendering:', context);
+    });
+  },
+});
+
+export default myRuntimePlugin;
+```
+
+## 注册插件
+
+在项目 `src/modern.runtime.ts` 文件中注册插件：
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import myRuntimePlugin from './plugins/myRuntimePlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myRuntimePlugin()],
+});
+```
+
+## 应用场景 -- 全局数据注入
+
+通过 `onBeforeRender` 钩子的 `context` 参数，可以向应用注入全局数据。应用的组件可以通过 `useRuntimeContext` Hook 访问这些数据。
+
+:::info
+
+此功能在以下场景中特别有用：
+* 需要页面级前置数据的应用
+* 自定义数据注入流程
+* 框架迁移场景（例如从 Next.js 迁移）
+
+:::
+
+**定义数据注入插件**
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const dataInjectionPlugin = (): RuntimePluginFuture => ({
+  name: 'data-injection-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      // 向 context 中注入数据
+      context.message = 'Hello World';
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```
+
+**在组件中使用注入的数据**
+
+```tsx
+import { useRuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = useRuntimeContext();
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```
+
+**结合 SSR 使用**
+
+在 SSR 场景下，浏览器端可以获取服务端渲染期间通过 `onBeforeRender` 注入的数据。开发者可以根据需求决定是否在浏览器端重新获取数据来覆盖服务端数据。
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const dataInjectionPlugin = (): RuntimePluginFuture => ({
+  name: 'data-injection-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      if (process.env.MODERN_TARGET === 'node') {
+        // 服务端渲染时设置数据
+        context.message = 'Hello World By Server';
+      } else {
+        // 客户端渲染时检查数据
+        if (!context.message) {
+          // 如果没有获取到服务端数据，则设置客户端数据
+          context.message = 'Hello World By Client';
+        }
+      }
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```
+
+## 兼容性说明
+
+在 Modern.js 的早期版本中，支持通过 `routes/layout.tsx` 中的 `init` 钩子以及 `App.init` 方法来添加渲染预处理逻辑。这些方式目前仍然**被支持**，但我们**强烈推荐**使用 Runtime 插件实现。
+
+:::warning
+
+未来版本中，`routes/layout.tsx` 的 `init` 钩子和 `App.init` 方法将逐步**废弃**。建议尽早迁移到 Runtime 插件方案。
+:::