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

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

@@ -0,0 +1,239 @@
+# 插件系统
+
+Modern.js 采用高度可扩展的插件化架构，其核心功能和扩展能力均通过插件实现。插件系统不仅保证了框架的灵活性，也为开发者提供了强大的定制化手段。本文将重点介绍如何编写 Modern.js 插件，帮助您快速上手插件开发。
+
+## 核心理念：一切皆插件
+
+Modern.js 秉承“一切皆插件”的设计哲学，将框架的各项功能模块化，通过插件的形式进行组装和扩展。这种设计带来了诸多优势，包括：
+
+-   **高内聚，低耦合**：各功能模块独立开发、测试和维护，降低系统复杂度。
+-   **灵活可扩展**：用户可通过编写或组合插件，轻松定制框架行为，无需修改核心代码。
+-   **易于复用**：插件可跨项目共享，提高开发效率。
+-   **渐进式增强**：按需引入插件，无需一开始就承载所有功能的复杂性。
+
+## 插件类型与适用场景
+
+Modern.js 提供了三种主要插件类型，分别对应应用开发的不同阶段：
+
+**CLI 插件**：
+    -   **作用阶段**：构建时（执行 `modern` 命令时）。
+    -   **典型场景**：
+        -   扩展命令行工具。
+        -   修改构建配置。
+        -   监听文件变化。
+        -   控制构建流程。
+    -   **配置方式**：`modern.config.ts` 中的 `plugins` 字段。
+
+**Runtime 插件**：
+    -   **作用阶段**：应用运行时（浏览器/Node.js 环境）。
+    -   **典型场景**：
+        -   初始化全局状态或服务。
+        -   封装 React 高阶组件（HOC）。
+        -   拦截或修改路由行为。
+        -   控制渲染流程。
+    -   **配置方式**：`src/modern.runtime.ts` 中的 `plugins` 字段。
+
+{/* **Server 插件**：
+    -   **作用阶段**：服务端请求处理阶段。
+    -   **典型场景**：
+        -   添加自定义中间件。
+        -   扩展服务端 API。
+        -   定制化 SSR 逻辑。
+        -   与后端框架集成。
+    -   **配置方式**：`server/modern.server.ts` 中的 `plugins` 字段。 */}
+
+## 插件结构
+
+一个典型的 Modern.js 插件包含以下几个关键部分：
+
+```ts
+import type { Plugin } from '@modern-js/plugin-v2';
+
+const myPlugin: Plugin = {
+  name: 'my-awesome-plugin', // 插件的唯一标识符（必需）
+
+  // 插件依赖和执行顺序（可选）
+  pre: [],    // 在此插件之前执行的插件名列表，默认为空数组
+  post: [],   // 在此插件之后执行的插件名列表，默认为空数组
+  required: [],// 必需的插件列表，若依赖的插件未注册，则会报错，默认为空数组
+  usePlugins: [], // 内部使用的插件实例列表，默认为空数组
+
+  // 注册新的 Hook (可选)
+  registryHook: {},
+
+  // 插件的入口函数（必需）
+  setup(api) {
+    // 插件的核心逻辑，通过 api 对象调用插件 API
+    api.modifyWebpackConfig(config => { /* ... */ });
+    api.onPrepare(() => { /* ... */ });
+    // ... 其他 API 调用
+  },
+};
+
+export default myPlugin;
+```
+
+**字段说明：**
+
+##### `name`
+
+- 类型： `string`
+- 说明：标识插件的名称。在插件体系中，该名称必须唯一，否则将导致插件加载失败。
+
+:::info
+后续 `pre`, `post`, `required` 中声明的插件名称都是这里的 name 字段.
+:::
+
+##### `setup`
+
+- 类型： `(api: PluginAPI) => MaybePromise<void>`
+- 说明：插件逻辑的主要入口。
+
+###### `api`
+
+- 类型： `PluginAPI`
+- 说明：插件的 API，包含插件支持的 Hooks 和工具函数。
+
+##### `pre`
+
+- 类型： `string[]`
+- 说明：用于插入插件执行顺序。在 `pre` 中声明的插件会在此插件之前执行。
+
+##### `post`
+
+- 类型： `string[]`
+- 说明：用于确定插件执行顺序。在 `post` 中声明的插件会在此插件之后执行。
+
+##### `required`
+
+- 类型： `string[]`
+- 说明：该插件依赖的其它插件。在运行前，会校验依赖的插件是否已注册。
+
+:::info
+如果在 `pre` 或 `post` 中配置了未注册的插件名，这些插件名将被**自动忽略**，不会影响其他插件的执行。
+
+如果需要明确声明当前插件依赖的插件必须存在，需要使用 `required` 字段。
+:::
+
+##### `usePlugins`
+
+- 类型： `Plugin`
+- 说明：主动在插件中注册其他相同类型的插件。
+
+:::info
+`usePlugins` 中声明的插件默认在当前插件之前执行。需要在其后执行，请使用 `post` 声明。
+:::
+
+##### `registryHooks`
+
+- 类型： `Record<string, PluginHook<(...args: any[]) => any>>`
+- 说明：扩展当前支持的 Hook 函数，以实现自定义功能。
+
+
+## 插件 Hook 模型
+
+Modern.js 插件系统的核心是其 Hook 模型，它定义了插件之间的通信机制。Modern.js 主要提供两种 Hook 类型：
+
+### Async Hook（异步 Hook）
+
+-   **特点**：
+    -   Hook 函数异步执行，支持 `async/await`。
+    -   前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
+    -   最终返回最后一个 Hook 函数的返回值。
+-   **适用场景**：涉及异步操作的场景（如网络请求、文件读写等）。
+-   **创建方式**：使用 `createAsyncHook` 创建。
+
+示例：
+
+```ts
+// 定义 Hooks
+import { createAsyncHook } from '@modern-js/plugin-v2';
+
+export type AfterPrepareFn = () => Promise<void> | void;
+export const onAfterPrepare = createAsyncHook<AfterPrepareFn>();
+
+// 插件中注册 Hooks
+const myPlugin = () => ({
+  name: "my-plugin",
+  registryHooks: {
+    onAfterPrepare,
+  },
+  setup: (api) => {
+    api.onPrepare(async () => {
+      // 插件中使用注册的 Hooks
+      const hooks = api.getHooks();
+      await hooks.onAfterPrepare.call();
+    });
+  }
+});
+
+// 在其他插件中使用 Hook
+const myPlugin2 = () => ({
+  name: "my-plugin-2",
+  setup: (api) => {
+    api.onAfterPrepare(async () => {
+      // TOOD
+    });
+  }
+})
+```
+
+### Sync Hook（同步 Hook）
+
+-   **特点**：
+    -   Hook 函数同步执行。
+    -   前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
+    -   最终返回最后一个 Hook 函数的返回值。
+-   **适用场景**：需要同步修改数据的场景（如修改配置、路由等）。
+-   **创建方式**：使用 `createSyncHook` 创建。
+
+示例：
+
+```ts
+// 定义 Hooks
+import { createSyncHook } from '@modern-js/plugin-v2';
+
+type RouteObject = {/** TODO **/};
+const modifyRoutes = createSyncHook<(routes: RouteObject[]) => RouteObject[]>();
+
+// 插件中注册 Hooks
+const myPlugin = () => ({
+  name: "my-plugin",
+  registryHooks: {
+    modifyRoutes,
+  },
+  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;
+    });
+  }
+});
+```
+
+## 插件开发最佳实践
+
+- **单一职责**: 每个插件应该专注于实现一个特定的、内聚的功能。避免创建功能庞杂、职责不清的插件。
+- **命名规范**: 插件名称应清晰、简洁, 并遵循一定的命名约定 (如 `plugin-xxx` 或 `@scope/plugin-xxx`).
+- **类型安全**: 充分利用 TypeScript 的类型系统, 确保插件 API 的类型安全, 减少运行时错误。
+- **文档完善**: 为插件编写清晰的文档, 包括 API 说明、使用示例、配置项解释以及变更日志。
+- **测试充分**: 对插件进行单元测试和集成测试, 确保其稳定性、可靠性以及在各种场景下的兼容性。
+- **减少副作用**: 插件应该尽可能地减少对外部环境的修改 (如全局变量、文件系统等), 保持插件的独立性和可移植性。
+- **错误处理**: 插件内部应该妥善处理可能出现的错误, 避免因为插件的异常导致整个应用崩溃。
+- **性能优化**: 注意插件的性能影响, 避免不必要的计算和资源消耗, 特别是在循环或频繁调用的 Hook 中。
+- **版本控制**: 遵循语义化版本控制 (Semantic Versioning), 确保插件的向后兼容性, 方便用户升级。
+
+遵循这些最佳实践, 可以帮助您开发出高质量、易维护、易使用的 Modern.js 插件。

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

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

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

@@ -0,0 +1,166 @@
+# 插件 API
+
+Modern.js 的 Runtime 插件允许您在应用程序的 React 代码运行时扩展和修改其行为。通过 Runtime 插件，您可以轻松地执行初始化任务、实现 React 高阶组件（HOC）封装等功能。
+
+## 插件结构
+
+一个典型的 Runtime 插件如下所示：
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const myRuntimePlugin = (): RuntimePluginFuture => ({
+  name: 'my-runtime-plugin',
+  setup: (api) => {
+    // 使用 api 注册钩子
+    api.onBeforeRender((context) => {
+      console.log('Before rendering:', context);
+    });
+
+    api.wrapRoot((App) => {
+      return (props) => (
+        <MyContextProvider>
+          <App {...props} />
+        </MyContextProvider>
+      );
+    });
+  },
+});
+
+export default myRuntimePlugin;
+
+```
+
+-   `name`： 插件的唯一标识符。
+-   `setup`： 插件的主要逻辑，接收一个 `api` 对象作为参数，用于注册钩子。
+
+## API 概览
+
+Runtime 插件 API 主要分为以下几类：
+
+-   **信息获取**：获取运行时配置和钩子函数。
+-   **生命周期钩子**：在应用渲染的不同阶段执行自定义逻辑。
+
+### 信息获取
+
+#### `api.getRuntimeConfig`
+
+获取用户在 `modern.runtime.ts` 文件中定义的运行时配置。
+
+-   **用法**:
+
+```ts
+const config = api.getRuntimeConfig();
+console.log(config.myCustomSetting);
+```
+
+:::warning
+
+此方法返回的是用户配置的副本，修改返回值不会影响原始配置。
+:::
+
+#### `api.getHooks`
+
+获取可用于手动触发的钩子函数。
+
+-   **类型：**
+
+```ts
+() => {
+  onBeforeRender: { call: (context: any) => Promise<void> };
+  // 其他钩子...
+};
+```
+
+-   **用法：**
+
+```ts
+const hooks = api.getHooks();
+await hooks.onBeforeRender.call(myContext);
+```
+
+### 生命周期钩子
+
+#### `api.onBeforeRender`
+
+在应用渲染（包括服务器端渲染和客户端渲染）之前执行。您可以在此钩子中执行数据预取、修改渲染上下文等操作。
+
+-   **类型：**
+
+    ```ts
+    type OnBeforeRenderFn<RuntimeContext> = (context: RuntimeContext) => Promise<void> | void;
+    ```
+    `RuntimeContext` 包含当前请求的上下文信息，如请求对象、响应对象等。
+
+-   **用法：**
+
+    ```ts
+    api.onBeforeRender(async (context) => {
+      const data = await fetchData(context.req);
+      context.data = data; // 将数据添加到上下文中
+    });
+    ```
+
+:::warning
+
+- 此钩子在每次渲染前都会执行，因此应避免执行耗时过长的操作。
+- 您可以在此钩子中修改 `context` 对象，并将修改后的 `context` 传递给后续的渲染过程。
+
+:::
+
+#### `api.wrapRoot`
+
+允许您使用自定义的 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;
+    });
+    ```
+
+:::warning
+
+-   **务必将 `props` 传递给原始的 `App` 组件**，否则可能导致应用无法正常工作。
+-  `wrapRoot` 返回的组件会在每次渲染时重新创建，因此应避免在其中定义复杂的逻辑或状态。
+
+:::
+
+## 进阶用法
+
+### 组合使用钩子
+
+您可以组合使用多个钩子来实现更复杂的功能。例如，您可以使用 `onBeforeRender` 获取数据，然后使用 `wrapRoot` 将数据通过 Context 传递给整个应用：
+
+```ts
+api.onBeforeRender(async (context) => {
+  const data = await fetchData(context.req);
+  context.data = data;
+});
+
+api.wrapRoot((App) => {
+  return (props) => (
+    <DataContext.Provider value={props.data}>
+      <App {...props} />
+    </DataContext.Provider>
+  );
+});
+```

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

@@ -0,0 +1,29 @@
+# 生命周期
+
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    init{{"Runtime 初始化"}}
+    load_config(加载用户配置文件)
+    runtime_plugin(加载 Runtime 插件<br><sub>配置文件中注册的插件<br>CLI 插件注册的 Runtime 插件<br>插件中使用的插件</sub>)
+    registry_hooks(注册 Hooks 函数<br><sub>执行插件 setup 函数，注册插件中定义的 Hook, 插件 setup 中逻辑也会在这里执行</sub>)
+
+    wrapRoot(wrapRoot<br><sub>wrapRoot 中返回组件中的逻辑会在组件渲染时执行</sub>)
+    onBeforeRender(onBeforeRender)
+
+    init --> load_config
+    load_config --> runtime_plugin
+    runtime_plugin --> registry_hooks
+    registry_hooks --> wrapRoot
+    wrapRoot --> onBeforeRender
+
+    style init fill:#FDE68A,font-size:10px;
+    style load_config stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style runtime_plugin stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style registry_hooks stroke-dasharray:5 5,fill:#9CA3AF,font-size:10px;
+    style wrapRoot font-size:10px;
+    style onBeforeRender font-size:10px;
+`}
+</Mermaid>

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

@@ -0,0 +1,101 @@
+# 插件迁移
+
+### 迁移背景
+
+Modern.js 插件系统持续演进，为了提供更清晰的 API 和更强大的功能，我们对 Runtime 插件的定义和使用方式进行了优化。虽然旧版插件写法部分仍被兼容，但我们强烈建议您按照本指南进行迁移，以充分利用新版插件系统的优势。
+
+### 迁移步骤总览
+
+1.  **更新插件类型定义**：将 `Plugin` 类型替换为 `RuntimePluginFuture`。
+2.  **调整 Hooks 调用方式**：从 `return hooks` 模式迁移到 `api.xxx` 直接调用。
+3.  **替换已变更的 API**：参照详细的 API 映射表，更新您的代码。
+
+### 详细迁移步骤
+
+#### 更新插件类型定义
+
+这是迁移的第一步，也是最关键的一步。它确保您的插件能够与新版插件系统正确交互。
+
+```typescript
+// 旧版写法
+import type { Plugin } from '@modern-js/runtime';
+
+const plugin: Plugin = { ... };
+
+// 新版写法
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const plugin: RuntimePluginFuture = { ... };
+```
+
+**说明：** `RuntimePluginFuture` 类型是新版插件的标准定义，它带来了更好的类型推断和更清晰的 API 结构。
+
+#### 调整 Hooks 调用方式
+
+新版插件系统推荐使用 `api` 对象直接调用 Hooks，这种方式更直观、更易于维护。
+
+```typescript
+// 旧版写法 (return hooks)
+{
+  setup: () => ({
+    beforeRender({ req, res }) { /*...*/ }
+  })
+}
+
+// 新版写法 (api.xxx)
+{
+  setup: api => {
+    api.onBeforeRender(({ req, res }) => { /*...*/ })
+  }
+}
+```
+
+**说明：** `api` 对象提供了所有可用的 Hooks 和工具方法。
+
+#### 替换已变更的 API
+
+为了保持 API 的一致性和清晰性，我们对部分 API 的名称进行了调整。同时，`hoc` 和 `init` 这两个 Hook 已被移除，请使用新的 Hook 进行替代。下表列出了所有变更的 API 及其新旧对应关系：
+
+| 旧版 API      | 新版 API          | 说明                                                                                                                     |
+| :------------ | :---------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `beforeRender` | `onBeforeRender`  | 在应用渲染前执行。                                                                                                       |
+| `hoc`         | `wrapRoot`        | **重要变更：** 用于包裹根组件，实现高阶组件 (HOC) 的功能。请确保将 props 传递给原始组件。                               |
+| `init`        | `onBeforeRender`  | **重要变更：** 在应用渲染前执行初始化逻辑。                                                                                 |
+
+**说明：**
+- `onBeforeRender` 替代了原来的 `beforeRender` 和 `init`，分别用于渲染前逻辑和初始化。
+- `wrapRoot` 替代了 `hoc`，用于实现高阶组件功能，使用时务必注意 props 的传递。
+
+**`wrapRoot` 使用示例：**
+
+```typescript
+{
+  setup: api => {
+    api.wrapRoot((App) => {
+      const AppWrapper = (props) => {
+        // 确保将 props 传递给原始组件
+        return <Provider value={xx}><App {...props}/></Provider>;
+      };
+      return AppWrapper;
+    });
+  }
+}
+```
+
+### 常见问题解答
+
+**Q: 迁移后，我的插件还能正常工作吗？**
+
+A: 只要您按照本指南正确完成了所有步骤，您的插件应该能够正常工作。如果您遇到任何问题，请查阅 Modern.js 的官方文档或寻求社区支持。
+
+**Q: 我必须立即迁移我的插件吗？**
+
+A: 虽然旧版插件写法仍然兼容，但我们强烈建议您尽快迁移。新版插件系统提供了更好的性能和更丰富的功能，长期来看，迁移是值得的。
+
+**Q: 我可以在哪里找到更多关于新版插件系统的信息？**
+
+A: 请查阅 Modern.js 的官方文档，特别是关于插件系统的部分。您也可以参考其他已迁移的插件示例，了解最佳实践。
+
+### 总结
+
+通过这份详细的迁移指南，我们希望能够帮助您顺利地将您的 Runtime 插件迁移到 Modern.js 的新版插件系统。如果您在迁移过程中遇到任何问题，请随时向我们寻求帮助。

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

@@ -0,0 +1,3 @@
+# 插件 API
+
+敬请期待...

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

@@ -0,0 +1,3 @@
+# 生命周期
+
+敬请期待...

package/i18n.json

@@ -91,6 +91,10 @@
     "zh": "插件系统",
     "en": "Plugin System"
   },
+  "official-plugins": {
+    "zh": "官方插件",
+    "en": "Official Plugins"
+  },
   "cli-plugins": {
     "zh": "CLI 插件",
     "en": "CLI Plugins"

package/package.json

@@ -15,13 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.65.5",
+  "version": "2.66.1-alpha.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.65.5"
+    "mermaid": "^11.4.1",
+    "@modern-js/sandpack-react": "2.66.0"
   },
   "devDependencies": {
     "@rspress/shared": "1.42.0",

package/src/components/Footer/index.tsx

@@ -76,7 +76,7 @@ export default function Footer() {
         },
         {
           label: t('pluginSystem'),
-          to: useUrl('/plugin/plugin-system/introduction'),
+          to: useUrl('/plugin/plugin-system'),
         },
         {
           label: t('projectGenerator'),

package/src/components/Mermaid/index.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import type { CSSProperties, PropsWithChildren } from 'react';
+import './style.scss';
+
+import mermaid, { type MermaidConfig } from 'mermaid';
+import { useEffect, useId, useState } from 'react';
+interface Props {
+  style?: CSSProperties;
+  title?: string;
+  config?: MermaidConfig;
+}
+export default function Mermaid({
+  style,
+  children,
+  title,
+  config,
+}: PropsWithChildren<Props>) {
+  const id = useId();
+  const [svg, setSvg] = useState('');
+  const [renderError, setRenderError] = useState(false);
+
+  async function renderMermaid2SVG() {
+    // https://github.com/mermaid-js/mermaid/blob/1b40f552b20df4ab99a986dd58c9d254b3bfd7bc/packages/mermaid/src/docs/.vitepress/theme/Mermaid.vue#L53
+    const hasDarkClass = document.documentElement.classList.contains('dark');
+
+    const mermaidConfig: MermaidConfig = {
+      securityLevel: 'loose',
+      startOnLoad: false,
+      theme: hasDarkClass ? 'dark' : 'default',
+      ...config,
+    };
+
+    try {
+      mermaid.initialize(mermaidConfig);
+
+      const { svg } = await mermaid.render(
+        id.replace(/:/g, ''),
+        children as string,
+      );
+
+      setSvg(svg);
+    } catch (error) {
+      setRenderError(true);
+    }
+  }
+
+  useEffect(() => {
+    renderMermaid2SVG();
+  }, [children]);
+  return (
+    <>
+      {renderError || !svg ? null : (
+        <div style={style} className="modern-mermaid">
+          <h3>{title}</h3>
+          <div dangerouslySetInnerHTML={{ __html: svg }} />
+        </div>
+      )}
+    </>
+  );
+}