@modern-js/main-doc 2.65.5 → 2.66.1-alpha.0

package/docs/zh/components/micro-runtime-config.mdx

@@ -1,7 +1,7 @@
-```js title="src/App.tsx"
-import { defineConfig } from '@modern-js/runtime';
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-defineConfig(App, {
+export default defineRuntimeConfig({
   masterApp: {
     apps: [{
       name: 'Table',

package/docs/zh/components/reduck-notify.mdx

@@ -0,0 +1,27 @@
+:::warning
+从 `MAJOR_VERSION.67.0` 起，Modern.js 不再默认提供 Reduck 状态管理能力。如果需要使用 Reduck，您需要安装并注册 state 插件。
+
+**安装步骤**
+
+1. 安装 `@modern-js/plugin-state` 依赖：
+
+```bash
+pnpm add @modern-js/plugin-state
+```
+
+2. 注册 state 插件：
+
+```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/configure/app/plugins.mdx

@@ -9,7 +9,7 @@ sidebar_position: 9
 
 用于配置自定义的 Modern.js 框架插件。
 
-自定义插件的编写方式请参考 [如何编写插件](/plugin/plugin-system/implement)。
+自定义插件的编写方式请参考 [如何编写插件](/plugin/plugin-system)。
 
 ## 注意事项
 
@@ -33,7 +33,7 @@ Modern.js 中内置了三种不同的框架插件：
 
 默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
 
-当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](/plugin/plugin-system/relationship)。
+当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件结构](/plugin/plugin-system)。
 
 ## 示例
 

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

@@ -1,120 +1,101 @@
----
-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 配置：
-
-:::info
-当 runtime 配置中存在函数时，只能使用该方式进行配置。
-
-:::
+## 多入口配置
 
-import { Tabs, Tab as TabItem } from "@theme";
+对于多入口应用，`defineRuntimeConfig` 函数可以根据入口名称返回特定的配置：
 
-<Tabs>
-  <TabItem value="layout" label="约定式路由" default>
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-```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
+## 配置方式演进
 
-- **类型：** `Object`
-- **默认值：**无
+在 MAJOR_VERSION.66.0 之前，运行时配置分散在多个位置：
 
-#### 说明
+1. `modern.config.ts` 中的 `runtime` 和 `runtimeByEntries` 字段
+2. 各入口的 `App.config` 或 `layout` 文件导出的 `config` 函数
 
-按入口添加 runtime 配置，选项属性同 runtime 一致，指定值会和 runtime 属性内容做替换合并操作。
+为提升可维护性，Modern.js 引入了统一的 `src/modern.runtime.ts` 配置入口。
 
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
+### 旧配置方式（兼容但不推荐）
 
-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/tools/esbuild.mdx

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [esbuild 插件配置](/plugin/rsbuild-plugins/plugin-esbuild#配置)。
+完整配置项请参考 [esbuild 插件配置](/plugin/official/rsbuild-plugins/plugin-esbuild#配置)。

package/docs/zh/configure/app/tools/swc.mdx

@@ -108,4 +108,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [SWC 插件配置](/plugin/cli-plugins/plugin-swc.html#配置)。
+完整配置项请参考 [SWC 插件配置](/plugin/official/cli-plugins/plugin-swc.html#配置)。

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/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 插件方案。
+:::

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

@@ -483,101 +483,6 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 :::
 
 
-## 运行时配置
-
-{/* Todo 移到动运行时配置章节 */}
-
-在根 `<Layout>` 组件中（`routes/layout.ts`），可以动态地定义运行时配置：
-
-```tsx title="src/routes/layout.tsx"
-// 定义运行时配置
-import type { AppConfig } from '@modern-js/runtime';
-
-export const config = (): AppConfig => {
-  return {
-    router: {
-      createRoutes() {
-        return [
-          {
-            path: 'modern',
-            element: <div>modern</div>,
-          },
-        ];
-      },
-    },
-  };
-};
-```
-
-## 渲染前的钩子
-
-{/* Todo 移到动运行时配置章节 */}
-
-在有些场景下，需要在应用渲染前做一些操作，可以在 `routes/layout.tsx` 中定义 `init` 钩子，`init` 在客户端和服务端均会执行，基本使用示例如下：
-
-```ts title="src/routes/layout.tsx"
-import type { RuntimeContext } from '@modern-js/runtime';
-
-export const init = (context: RuntimeContext) => {
-  // do something
-};
-```
-
-通过 `init` 钩子可以挂载一些全局的数据，在应用的其他地方可以访问 `runtimeContext` 变量：
-
-:::note
-该功能在应用需要页面前置的数据、自定义数据注入或是框架迁移（如 Next.js）时会非常有用。
-
-:::
-
-```ts title="src/routes/layout.tsx"
-import { RuntimeContext } from '@modern-js/runtime';
-
-type InitialData = {
-  message: string;
-}
-
-export const init = (context: RuntimeContext): InitialData => {
-  return {
-    message: 'Hello World',
-  };
-};
-```
-
-```tsx title="src/routes/page.tsx"
-import { useRuntimeContext } from '@modern-js/runtime';
-
-export default () => {
-  const context = useRuntimeContext();
-  const { message } = context.initialData as InitialData;
-
-  return <div>{message}</div>;
-};
-```
-
-配合 SSR 功能时，浏览器端可以获取到 SSR 时 `init` 返回的数据，开发者可以自行判断是否要在浏览器端重新获取数据来覆盖 SSR 数据，例如：
-
-```tsx title="src/routes/layout.tsx"
-import type { RuntimeContext } from '@modern-js/runtime';
-
-export const init = (runtimeContext: RuntimeContext) => {
-  if (process.env.MODERN_TARGET === 'node') {
-    return {
-      message: 'Hello World By Server',
-    };
-  } else {
-    const { context } = runtimeContext;
-    const data = context.getInitData();
-    // 如果没有获取到期望的数据
-    if (!data.message) {
-      return {
-        message: 'Hello World By Client',
-      };
-    }
-  }
-};
-```
-
 import Motivation from '@site-docs/components/convention-routing-motivation';
 
 <Motivation />

package/docs/zh/guides/topic-detail/micro-frontend/c02-development.mdx

@@ -14,9 +14,9 @@ title: 体验微前端
 
 目前项目的路由模式分为以下三种
 
-- 约定式路由 (设置 `router: true` 并使用文件路由)
-- 自控式路由 (设置 `router: true` 并自己创建 `BrowserRouter` 等)
-- 其他 (设置 `router: false` 项目内自己安装和使用 `react-router-dom`)
+- [约定式路由](/guides/concept/entries.html#约定式路由)
+- [自控式路由](/guides/concept/entries.html#自控式路由)
+- 其他 (项目自行安装和使用 `react-router-dom`)
 
 在本教程中我们会为主应用创建两个子应用 Table 和 Dashboard (Table 为约定式路由，Dashboard 为自控式路由)
 
@@ -206,7 +206,6 @@ export default defineConfig({
   },
   runtime: {
     router: true,
-    state: true,
   },
   deploy: {
     microFrontend: true,
@@ -259,7 +258,6 @@ export default defineConfig({
   },
   runtime: {
     router: true,
-    state: true,
   },
   deploy: {
     microFrontend: true,

package/docs/zh/guides/topic-detail/micro-frontend/c03-main-app.mdx

@@ -35,8 +35,10 @@ import MicroRuntimeConfig from '@site-docs/components/micro-runtime-config';
 
 通过该函数可以拉取远程的子应用列表，并将其注册至运行时框架：
 
-```ts title="App.tsx"
-defineConfig(App, {
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
   masterApp: {
     manifest: {
       getAppList: async () => {