@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/zh/plugin/plugin-system.mdx

@@ -6,15 +6,13 @@ Modern.js 采用高度可扩展的插件化架构，其核心功能和扩展能
 
 Modern.js 秉承“一切皆插件”的设计哲学，将框架的各项功能模块化，通过插件的形式进行组装和扩展。这种设计带来了诸多优势，包括：
 
--   **高内聚，低耦合**：各功能模块独立开发、测试和维护，降低系统复杂度。
--   **灵活可扩展**：用户可通过编写或组合插件，轻松定制框架行为，无需修改核心代码。
--   **易于复用**：插件可跨项目共享，提高开发效率。
--   **渐进式增强**：按需引入插件，无需一开始就承载所有功能的复杂性。
+- **高内聚，低耦合**：各功能模块独立开发、测试和维护，降低系统复杂度。
+- **灵活可扩展**：用户可通过编写或组合插件，轻松定制框架行为，无需修改核心代码。
+- **易于复用**：插件可跨项目共享，提高开发效率。
+- **渐进式增强**：按需引入插件，无需一开始就承载所有功能的复杂性。
 
 ## 插件类型与适用场景
 
-Modern.js 提供了三种主要插件类型，分别对应应用开发的不同阶段：
-
 **CLI 插件**：
     -   **作用阶段**：构建时（执行 `modern` 命令时）。
     -   **典型场景**：
@@ -47,25 +45,29 @@ Modern.js 提供了三种主要插件类型，分别对应应用开发的不同
 一个典型的 Modern.js 插件包含以下几个关键部分：
 
 ```ts
-import type { Plugin } from '@modern-js/plugin-v2';
+import type { Plugin } from '@modern-js/plugin';
 
 const myPlugin: Plugin = {
   name: 'my-awesome-plugin', // 插件的唯一标识符（必需）
 
   // 插件依赖和执行顺序（可选）
-  pre: [],    // 在此插件之前执行的插件名列表，默认为空数组
-  post: [],   // 在此插件之后执行的插件名列表，默认为空数组
-  required: [],// 必需的插件列表，若依赖的插件未注册，则会报错，默认为空数组
+  pre: [], // 在此插件之前执行的插件名列表，默认为空数组
+  post: [], // 在此插件之后执行的插件名列表，默认为空数组
+  required: [], // 必需的插件列表，若依赖的插件未注册，则会报错，默认为空数组
   usePlugins: [], // 内部使用的插件实例列表，默认为空数组
 
   // 注册新的 Hook (可选)
-  registryHook: {},
+  registryHooks: {},
 
   // 插件的入口函数（必需）
   setup(api) {
     // 插件的核心逻辑，通过 api 对象调用插件 API
-    api.modifyWebpackConfig(config => { /* ... */ });
-    api.onPrepare(() => { /* ... */ });
+    api.modifyRspackConfig(config => {
+      /* ... */
+    });
+    api.onPrepare(() => {
+      /* ... */
+    });
     // ... 其他 API 调用
   },
 };
@@ -129,98 +131,88 @@ export default myPlugin;
 - 类型： `Record<string, PluginHook<(...args: any[]) => any>>`
 - 说明：扩展当前支持的 Hook 函数，以实现自定义功能。
 
-
 ## 插件 Hook 模型
 
 Modern.js 插件系统的核心是其 Hook 模型，它定义了插件之间的通信机制。Modern.js 主要提供两种 Hook 类型：
 
 ### Async Hook（异步 Hook）
 
--   **特点**：
-    -   Hook 函数异步执行，支持 `async/await`。
-    -   前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
-    -   最终返回最后一个 Hook 函数的返回值。
--   **适用场景**：涉及异步操作的场景（如网络请求、文件读写等）。
--   **创建方式**：使用 `createAsyncHook` 创建。
+- **特点**：
+  - Hook 函数异步执行，支持 `async/await`。
+  - 前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
+  - 最终返回最后一个 Hook 函数的返回值。
+- **适用场景**：涉及异步操作的场景（如网络请求、文件读写等）。
+- **创建方式**：使用 `createAsyncHook` 创建。
 
 示例：
 
 ```ts
 // 定义 Hooks
-import { createAsyncHook } from '@modern-js/plugin-v2';
+import { createAsyncHook } from '@modern-js/plugin';
 
 export type AfterPrepareFn = () => Promise<void> | void;
 export const onAfterPrepare = createAsyncHook<AfterPrepareFn>();
 
 // 插件中注册 Hooks
 const myPlugin = () => ({
-  name: "my-plugin",
+  name: 'my-plugin',
   registryHooks: {
     onAfterPrepare,
   },
-  setup: (api) => {
+  setup: api => {
     api.onPrepare(async () => {
       // 插件中使用注册的 Hooks
       const hooks = api.getHooks();
       await hooks.onAfterPrepare.call();
     });
-  }
+  },
 });
 
 // 在其他插件中使用 Hook
 const myPlugin2 = () => ({
-  name: "my-plugin-2",
-  setup: (api) => {
+  name: 'my-plugin-2',
+  setup: api => {
     api.onAfterPrepare(async () => {
-      // TOOD
+      // TODO
     });
-  }
-})
+  },
+});
 ```
 
 ### Sync Hook（同步 Hook）
 
--   **特点**：
-    -   Hook 函数同步执行。
-    -   前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
-    -   最终返回最后一个 Hook 函数的返回值。
--   **适用场景**：需要同步修改数据的场景（如修改配置、路由等）。
--   **创建方式**：使用 `createSyncHook` 创建。
+- **特点**：
+  - Hook 函数同步执行。
+  - 前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
+  - 最终返回最后一个 Hook 函数的返回值。
+- **适用场景**：需要同步修改数据的场景（如修改配置、路由等）。
+- **创建方式**：使用 `createSyncHook` 创建。
 
 示例：
 
 ```ts
 // 定义 Hooks
-import { createSyncHook } from '@modern-js/plugin-v2';
+import { createSyncHook } from '@modern-js/plugin';
 
-type RouteObject = {/** TODO **/};
+type RouteObject = {
+  /** TODO **/
+};
 const modifyRoutes = createSyncHook<(routes: RouteObject[]) => RouteObject[]>();
 
 // 插件中注册 Hooks
 const myPlugin = () => ({
-  name: "my-plugin",
+  name: 'my-plugin',
   registryHooks: {
     modifyRoutes,
   },
-  setup: (api) => {
+  setup: api => {
     api.onPrepare(async () => {
       const routes = {};
       // 在插件中使用注册的 Hooks
       const hooks = api.getHooks();
       const routesResult = hooks.modifyRoutes.call(routes);
     });
-  }
-});
-
-// 其他插件使用 Hooks
-const myPlugin2 = () => ({
-  name: "my-plugin",
-  setup: (api) => {
-    api.modifyRoutes(async (routes) => {
-      // 修改 routes
-      return routes;
-    });
-  }
+  },
 });
 ```
 

package/docs/zh/plugin/runtime-plugins/_meta.json

@@ -1 +1 @@
-["api", "life-cycle", "migration"]
+["api", "life-cycle"]

package/docs/zh/plugin/runtime-plugins/api.mdx

@@ -13,18 +13,18 @@ Runtime 插件需要通过 `src/modern.runtime.ts` 中的 [`plugins`](/configure
 一个典型的 Runtime 插件如下所示：
 
 ```ts
-import type { RuntimePluginFuture } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
 
-const myRuntimePlugin = (): RuntimePluginFuture => ({
+const myRuntimePlugin = (): RuntimePlugin => ({
   name: 'my-runtime-plugin',
-  setup: (api) => {
+  setup: api => {
     // 使用 api 注册钩子
-    api.onBeforeRender((context) => {
+    api.onBeforeRender(context => {
       console.log('Before rendering:', context);
     });
 
-    api.wrapRoot((App) => {
-      return (props) => (
+    api.wrapRoot(App => {
+      return props => (
         <MyContextProvider>
           <App {...props} />
         </MyContextProvider>
@@ -34,18 +34,17 @@ const myRuntimePlugin = (): RuntimePluginFuture => ({
 });
 
 export default myRuntimePlugin;
-
 ```
 
--   `name`： 插件的唯一标识符。
--   `setup`： 插件的主要逻辑，接收一个 `api` 对象作为参数，用于注册钩子。
+- `name`： 插件的唯一标识符。
+- `setup`： 函数接收一个 `api` 对象，该对象提供了所有可用的 Runtime 插件 API。
 
 ## API 概览
 
 Runtime 插件 API 主要分为以下几类：
 
--   **信息获取**：获取运行时配置和钩子函数。
--   **生命周期钩子**：在应用渲染的不同阶段执行自定义逻辑。
+- **信息获取**：获取运行时配置和钩子函数。
+- **生命周期钩子**：在应用渲染的不同阶段执行自定义逻辑。
 
 ### 信息获取
 
@@ -53,7 +52,7 @@ Runtime 插件 API 主要分为以下几类：
 
 获取用户在 `modern.runtime.ts` 文件中定义的运行时配置。
 
--   **用法**:
+- **用法**:
 
 ```ts
 const config = api.getRuntimeConfig();
@@ -69,16 +68,18 @@ console.log(config.myCustomSetting);
 
 获取可用于手动触发的钩子函数。
 
--   **类型：**
+- **类型：**
 
 ```ts
 () => {
-  onBeforeRender: { call: (context: any) => Promise<void> };
+  onBeforeRender: {
+    call: (context: any) => Promise<void>;
+  }
   // 其他钩子...
 };
 ```
 
--   **用法：**
+- **用法：**
 
 ```ts
 const hooks = api.getHooks();
@@ -91,21 +92,24 @@ await hooks.onBeforeRender.call(myContext);
 
 在应用渲染（包括服务器端渲染和客户端渲染）之前执行。您可以在此钩子中执行数据预取、修改渲染上下文等操作。
 
--   **类型：**
+- **类型：**
 
-    ```ts
-    type OnBeforeRenderFn<RuntimeContext> = (context: RuntimeContext) => Promise<void> | void;
-    ```
-    `RuntimeContext` 包含当前请求的上下文信息，如请求对象、响应对象等。
+  ```ts
+  type OnBeforeRenderFn<RuntimeContext> = (
+    context: RuntimeContext,
+  ) => Promise<void> | void;
+  ```
 
--   **用法：**
+  `RuntimeContext` 包含当前请求的上下文信息，如请求对象、响应对象等。
 
-    ```ts
-    api.onBeforeRender(async (context) => {
-      const data = await fetchData(context.req);
-      context.data = data; // 将数据添加到上下文中
-    });
-    ```
+- **用法：**
+
+  ```ts
+  api.onBeforeRender(async context => {
+    const data = await fetchData(context.req);
+    context.data = data; // 将数据添加到上下文中
+  });
+  ```
 
 :::warning
 
@@ -118,35 +122,33 @@ await hooks.onBeforeRender.call(myContext);
 
 允许您使用自定义的 React 组件包裹应用的根组件。常用于添加全局的 Provider、布局组件等。
 
--   **类型：**
-
-    ```ts
-    type WrapRootFn = (
-      App: React.ComponentType<any>
-    ) => React.ComponentType<any>;
-    ```
-
--   **用法：**
-
-    ```ts
-    api.wrapRoot((App) => {
-      const AppWrapper = (props) => {
-        return (
-          <MyGlobalProvider>
-            <Layout>
-              <App {...props} /> {/* 确保传递 props */}
-            </Layout>
-          </MyGlobalProvider>
-        );
-      };
-      return AppWrapper;
-    });
-    ```
+- **类型：**
+
+  ```ts
+  type WrapRootFn = (App: React.ComponentType<any>) => React.ComponentType<any>;
+  ```
+
+- **用法：**
+
+  ```ts
+  api.wrapRoot(App => {
+    const AppWrapper = props => {
+      return (
+        <MyGlobalProvider>
+          <Layout>
+            <App {...props} /> {/* 确保传递 props */}
+          </Layout>
+        </MyGlobalProvider>
+      );
+    };
+    return AppWrapper;
+  });
+  ```
 
 :::warning
 
--   **务必将 `props` 传递给原始的 `App` 组件**，否则可能导致应用无法正常工作。
--  `wrapRoot` 返回的组件会在每次渲染时重新创建，因此应避免在其中定义复杂的逻辑或状态。
+- **务必将 `props` 传递给原始的 `App` 组件**，否则可能导致应用无法正常工作。
+- `wrapRoot` 返回的组件会在每次渲染时重新创建，因此应避免在其中定义复杂的逻辑或状态。
 
 :::
 
@@ -157,12 +159,12 @@ await hooks.onBeforeRender.call(myContext);
 您可以组合使用多个钩子来实现更复杂的功能。例如，您可以使用 `onBeforeRender` 获取数据，然后使用 `wrapRoot` 将数据通过 Context 传递给整个应用：
 
 ```ts
-import { RuntimePluginFuture, RuntimeReactContext } from '@modern-js/runtime';
+import { RuntimePlugin, RuntimeContext } from '@modern-js/runtime';
 import { useContext, createContext } from 'react';
 
 export const ThemeContext = createContext<{ theme: string } | null>(null);
 
-export const themePlugin = (): RuntimePluginFuture => {
+export const themePlugin = (): RuntimePlugin => {
   return {
     name: 'theme-plugin',
     setup: api => {
@@ -177,7 +179,7 @@ export const themePlugin = (): RuntimePluginFuture => {
 
       api.wrapRoot(App => {
         return props => {
-          const context = useContext(RuntimeReactContext);
+          const context = useContext(RuntimeContext);
           return (
             <ThemeContext.Provider value={context.data}>
               <App {...props} />

package/docs/zh/plugin/server-plugins/_meta.json

@@ -0,0 +1 @@
+["api", "life-cycle"]

package/docs/zh/plugin/server-plugins/api.mdx

@@ -1,3 +1,212 @@
 # 插件 API
 
-敬请期待...
+Modern.js 的 Server 插件允许您在服务端请求处理阶段扩展和定制功能，例如添加中间件、修改请求响应等。
+
+:::info
+
+Server 插件需要通过 `server/modern.server.ts` 中的 `plugins` 字段配置。
+
+:::
+
+## 插件基础结构
+
+一个典型的 Server 插件结构如下：
+
+```typescript
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+const myServerPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-server-plugin', // 插件名称，确保唯一性
+  setup: api => {
+    // 在这里使用 API 注册钩子、添加中间件等
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+      middlewares?.push({
+        name: 'my-middleware',
+        handler: async (c, next) => {
+          console.log('处理请求...');
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myServerPlugin;
+```
+
+- `name`： 插件的唯一标识符。
+- `setup` 函数接收一个 `api` 对象，该对象提供了所有可用的 Server 插件 API。
+
+## 信息获取
+
+#### `api.getServerContext`
+
+获取 Modern.js 服务器的上下文信息。
+
+- **返回值：** `ServerContext` 对象，包含以下字段：
+
+| 字段名            | 类型                | 描述                           |
+| ----------------- | ------------------- | ------------------------------ |
+| `middlewares`     | `MiddlewareObj[]`   | 中间件列表                     |
+| `renderMiddlewares` | `MiddlewareObj[]` | 渲染中间件列表                 |
+| `routes`          | `ServerRoute[]`     | 服务器路由信息                 |
+| `appDirectory`    | `string`            | 项目根目录的绝对路径           |
+| `apiDirectory`    | `string`            | API 模块目录的绝对路径         |
+| `lambdaDirectory` | `string`            | Lambda 模块目录的绝对路径     |
+| `sharedDirectory` | `string`            | 公共模块目录的绝对路径         |
+| `distDirectory`   | `string`            | 项目产物输出目录的绝对路径     |
+| `plugins`         | `ServerPlugin[]`    | 当前已注册的插件列表           |
+
+- **示例：**
+
+```typescript
+api.onPrepare(() => {
+  const serverContext = api.getServerContext();
+  console.log(`应用目录：${serverContext.appDirectory}`);
+  console.log(`已注册 ${serverContext.plugins.length} 个插件`);
+});
+```
+
+:::info
+`getServerContext` 返回的上下文信息是只读的，如需修改请使用 `updateServerContext`。
+:::
+
+---
+
+#### `api.getServerConfig`
+
+获取用户在 `server/modern.server.ts` 文件中定义的服务器配置。
+
+- **返回值：** 用户定义的服务器配置对象。
+- **示例：**
+
+```typescript
+api.onPrepare(() => {
+  const serverConfig = api.getServerConfig();
+  if (serverConfig.middlewares) {
+    console.log('用户自定义了中间件配置');
+  }
+});
+```
+
+---
+
+#### `api.getHooks`
+
+获取所有已注册的钩子函数。
+
+- **返回值：** 包含所有钩子函数的对象。
+- **示例：**
+
+```typescript
+const hooks = api.getHooks();
+// 手动触发 onPrepare 钩子
+await hooks.onPrepare.call();
+```
+
+:::warning
+在自定义插件中，只能手动调用对应插件注册的钩子，不能调用官方钩子，以免影响正常应用的执行顺序。
+:::
+
+---
+
+
+## 上下文修改
+
+#### `api.updateServerContext`
+
+更新服务器上下文信息。
+
+- **类型：** `api.updateServerContext(updateContext: DeepPartial<ServerContext>)`
+- **参数：**
+  - `updateContext`： 要更新的上下文对象（部分更新）。
+- **执行阶段：** 可在任何阶段使用。
+- **示例：**
+
+```typescript
+api.onPrepare(() => {
+  const context = api.getServerContext();
+  api.updateServerContext({
+    middlewares: [
+      ...context.middlewares,
+      {
+        name: 'new-middleware',
+        handler: async (c, next) => {
+          await next();
+        },
+      },
+    ],
+  });
+});
+```
+
+---
+
+
+## 生命周期钩子
+
+#### `api.onPrepare`
+
+在服务器准备阶段添加额外的逻辑。
+
+- **类型：** `api.onPrepare(prepareFn: () => void | Promise<void>)`
+- **参数：**
+  - `prepareFn`： 准备函数，无参数，可异步。
+- **执行阶段：** 在服务器完成配置校验之后，应用中间件之前。
+- **示例：**
+
+```typescript
+api.onPrepare(async () => {
+  const { middlewares } = api.getServerContext();
+
+  // 添加自定义中间件
+  middlewares.push({
+    name: 'request-logger',
+    handler: async (c, next) => {
+      const start = Date.now();
+      await next();
+      const duration = Date.now() - start;
+      console.log(`请求耗时: ${duration}ms`);
+    },
+  });
+});
+```
+
+:::info
+在 `onPrepare` 钩子中，可以修改 `getServerContext()` 返回的上下文对象（如 `middlewares`、`renderMiddlewares`），这些修改会在服务器启动时生效。
+:::
+
+---
+
+#### `api.onReset`
+
+在服务器重置时添加额外的逻辑。
+
+- **类型：** `api.onReset(resetFn: (params: { event: ResetEvent }) => void | Promise<void>)`
+- **参数：**
+  - `resetFn`： 重置处理函数，接收重置事件参数。
+    - `event.type`： 事件类型，可能的值：
+      - `'repack'`： 重新打包事件
+      - `'file-change'`： 文件变化事件
+    - `event.payload`： 当 `type` 为 `'file-change'` 时，包含文件变化信息数组。
+- **执行阶段：** 当文件发生变化或需要重新打包时。
+- **示例：**
+
+```typescript
+api.onReset(async ({ event }) => {
+  if (event.type === 'file-change') {
+    console.log('检测到文件变化:', event.payload);
+    // 执行清理或重新初始化操作
+  } else if (event.type === 'repack') {
+  }
+});
+```
+
+---
+
+
+## 其他说明
+
+- 可以参考 [Server 插件生命周期](./life-cycle.mdx) 了解插件钩子的执行顺序。
+- 中间件的执行顺序可以通过 `order` 字段控制（`'pre'`、`'default'`、`'post'`），也可以通过 `before` 字段指定在其他中间件之前执行。

package/docs/zh/plugin/server-plugins/life-cycle.mdx

@@ -1,3 +1,43 @@
 # 生命周期
 
-敬请期待...
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    init{{"Server 初始化"}}
+    load_config(加载用户配置文件)
+    server_plugin(加载 Server 插件<br><sub>配置文件中注册的插件<br>CLI 插件注册的 Server 插件<br>插件中使用的插件</sub>)
+    registry_hooks(注册 Hooks 函数<br><sub>执行插件 setup 函数，注册插件中定义的 Hook, 插件 setup 中逻辑也会在这里执行</sub>)
+
+    modifyConfig(modifyConfig<br><sub>修改服务器配置</sub>)
+    onPrepare(onPrepare<br><sub>在服务器完成配置校验之后，应用中间件之前执行</sub>)
+    apply_middlewares(应用中间件<br><sub>按照 order 和 before 规则应用中间件</sub>)
+
+    init --> load_config
+    load_config --> server_plugin
+    server_plugin --> registry_hooks
+    registry_hooks --> modifyConfig
+    modifyConfig --> onPrepare
+    onPrepare --> apply_middlewares
+
+    style init fill:#FDE68A,font-size:10px;
+    style load_config stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style server_plugin stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style registry_hooks stroke-dasharray:5 5,fill:#9CA3AF,font-size:10px;
+    style modifyConfig font-size:10px;
+    style onPrepare font-size:10px;
+    style apply_middlewares font-size:10px;
+`}
+</Mermaid>
+
+:::info
+
+**运行时钩子**
+
+`onReset` 钩子在运行时触发，当文件发生变化或需要代码重新编译(Rspack)完成时会被调用。它不属于初始化流程，因此未在上图中展示。
+
+- **触发时机**：文件变化（`event.type: 'file-change'`）或代码重新编译(Rspack)完成（`event.type: 'repack'`）
+- **使用场景**：清理缓存、重新初始化资源等
+
+:::

package/docs/zh/tutorials/_meta.json

@@ -1,14 +1,4 @@
 [
-  {
-    "type": "dir",
-    "name": "foundations",
-    "label": "foundations"
-  },
-  {
-    "type": "dir",
-    "name": "first-app",
-    "label": "first-app"
-  },
   {
     "type": "dir",
     "name": "examples",

package/docs/zh/tutorials/examples/csr-auth.mdx

@@ -4,7 +4,7 @@ title: 路由鉴权
 
 # 路由鉴权
 
-Modern.js 默认提供的路由方式是基于 React Router 6 的约定式路由，具体可查看[路由方案](/guides/basic-features/routes.html#路由方案)。
+Modern.js 默认提供的路由方式是基于 React Router v7 的约定式路由，具体可查看[路由方案](/guides/basic-features/routes/routes#路由方案)。
 
 在一个 Web 应用中如果存在多个路由，我们可能需要对部分路由进行鉴权后才能访问。例如下面这个案例：