@modern-js/main-doc 2.0.0-beta.2 → 2.0.0-beta.4

package/zh/{apis/app/runtime/plugin/hook-api.md → guides/topic-detail/framework-plugin/hook-list.md}

@@ -1,18 +1,13 @@
 ---
-sidebar_position: 5
+title: Hook 列表
+sidebar_position: 8
 ---
 
-# Hook API
+在 Modern.js 中暴露了三类插件：CLI、Runtime、Server。下面列举下各类中的 Hook：
 
-在 Modern.js 中主要构建了三套 Manager 模型：CLI、Runtime、Server，其中 CLI 是三套工程方案都有的，而 Runtime、Server 则是应用工程独有的，不同的工程方案中 Manager 模型的功能是不同的。
+## CLI
 
-## 基础
-
-这一部分的 Hook 模型是所有工程方案都有的，就是说在任意的工程方案中都可以在插件中添加实现对应的中间件函数。
-
-接下来对支持的所有基础 Hook 分别进行介绍。
-
-#### `config`
+### `config`
 
 - 功能：收集配置
 - 执行阶段：解析完 `modern.config.ts` 中的配置之后
@@ -38,7 +33,7 @@ export default (): CliPlugin => ({
 
 这里返回的配置信息，会被收集和统一处理合并。
 
-#### `validateSchema`
+### `validateSchema`
 
 - 功能：收集各个插件中配置的用来校验用户配置的 [JSON Schema](https://json-schema.org/)
 - 执行阶段：`config` Hook 运行完之后。
@@ -104,7 +99,7 @@ $ modern dev
     |   ^^^^^  Property foo is not expected to be here
 ```
 
-#### `prepare`
+### `prepare`
 
 - 功能：运行主流程的前置准备流程
 - 执行阶段：校验完配置之后
@@ -126,7 +121,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `commands`
+### `commands`
 
 - 功能：为 command 添加新的命令
 - 执行阶段：`prepare` Hook 运行完之后
@@ -168,7 +163,7 @@ $ modern foo
 foo
 ```
 
-#### `beforeExit`
+### `beforeExit`
 
 - 功能：在退出进程前，重置一些文件状态
 - 执行阶段：进程退出之前
@@ -190,17 +185,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-## 应用工程方案
-
-应用工程支持添加到项目中的插件主要有三种：CLI 插件、 Server 插件、Runtime 插件。他们是基于同一套插件系统实现的，但它们所支持的 Hook 不同、功能不同、运行的时机也不同。
-
-不同的 Manager 对应 Hook 模型和运行时机是不同的，所以接下来会对 CLI、Server、Runtime 的 Hook 模型分开讨论。
-
-### CLI
-
-应用工程中除了上面提到的基础的 CLI Hook 之外还有一些 MWA 场景下特定的 Hook。
-
-#### `beforeDev`
+### `beforeDev`
 
 - 功能：运行 dev 主流程的之前的任务
 - 执行阶段：`dev` 命令运行时，项目开始启动前执行
@@ -222,7 +207,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `afterDev`
+### `afterDev`
 
 - 功能：运行 dev 主流程的之后的任务
 - 执行阶段：`dev` 命令运行时，项目启动完成之后执行
@@ -244,7 +229,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `beforeCreateCompiler`
+### `beforeCreateCompiler`
 
 - 功能：在中间件函数中可以拿到创建 Webpack Compiler 的 Webpack 配置
 - 执行阶段：创建 Webpack Compiler 之前执行
@@ -266,7 +251,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `afterCreateCompiler`
+### `afterCreateCompiler`
 
 - 功能：在中间件函数中可以拿到创建的 Webpack Compiler
 - 执行阶段：创建 Webpack Compiler 之后执行
@@ -288,7 +273,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `beforePrintInstructions`
+### `beforePrintInstructions`
 
 - 功能：在中间件函数中可以拿到即将打印的日志信息，并对其进行修改
 - 执行阶段：打印日志信息之前执行
@@ -313,7 +298,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `beforeBuild`
+### `beforeBuild`
 
 - 功能：运行 build 主流程的之前的任务，可以拿到构建的 Webpack 配置
 - 执行阶段：`build` 命令运行时，项目构建启动前执行
@@ -335,7 +320,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `afterBuild`
+### `afterBuild`
 
 - 功能：运行 build 主流程的之后的任务
 - 执行阶段：`build` 命令运行时，项目构建完成之后执行
@@ -357,7 +342,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryImports`
+### `modifyEntryImports`
 
 - 功能：用于修改、添加生成入口文件中的 `import` 语句
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -389,7 +374,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryExport`
+### `modifyEntryExport`
 
 - 功能：用于修改生成入口文件中的 `export` 语句
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -416,7 +401,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryRuntimePlugins`
+### `modifyEntryRuntimePlugins`
 
 - 功能：用于添加、修改生成入口文件中的 [Runtime 插件](#Runtime)
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -451,7 +436,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryRenderFunction`
+### `modifyEntryRenderFunction`
 
 - 功能：用于修改生成入口文件中 `render` 函数
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -477,7 +462,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyFileSystemRoutes`
+### `modifyFileSystemRoutes`
 
 - 功能：用于修改生成前端页面路由文件中的内容，内容都是需要可序列化的
 - 执行阶段：生成前端路由文件之前，[`prepare`](#prepare) 阶段触发
@@ -511,7 +496,7 @@ export default (): CliPlugin => ({
 
 这样就为前端新增了一个页面路由。
 
-#### `modifyServerRoutes`
+### `modifyServerRoutes`
 
 - 功能：用于修改生成服务器路由中的内容
 - 执行阶段：生成 Server 路由文件之前，[`prepare`](#prepare) 阶段触发
@@ -544,7 +529,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyAsyncEntry`
+### `modifyAsyncEntry`
 
 - 功能：用于修改包裹入口文件的异步模块，参见 [source.enableAsyncEntry](/docs/configure/app/source/enable-async-entry)
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -570,7 +555,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `htmlPartials`
+### `htmlPartials`
 
 - 功能：用于定制生成的 HTML 页面模版
 - 执行阶段：[`prepare`](#prepare) 阶段触发
@@ -598,11 +583,15 @@ export default (): CliPlugin => ({
 
 这样就为 HTML 模版中新增了一个 Script 标签。
 
-### Server
+## Server
+
+:::note
+目前 Server 插件还未完全开放，API 不保证稳定，使用需谨慎。
+:::
 
 应用工程中的 Server 部分也支持了插件。其中的 Hook 将会提供一些特定阶段调用和特殊功能的 Hook。
 
-#### `create`
+### `create`
 
 - 功能：在中间件函数中会拿到 Server 初始化用到的指标测量工具配置 `measureOptions` 和日志工具配置 `loggerOptions`，并返回自定义的指标测量工具 `measure` 和日志工具配置 `logger`
 - 执行阶段：Server 初始化
@@ -624,7 +613,7 @@ export default (): ServerPlugin => ({
 });
 ```
 
-#### `prepareWebServer`
+### `prepareWebServer`
 
 - 功能：设置 Web 路由的处理函数，在中间件函数中可以拿到 Web Server 的前置中间件
 - 执行阶段：在请求到达的时候
@@ -650,7 +639,7 @@ export default (): ServerPlugin => ({
 });
 ```
 
-#### `prepareApiServer`
+### `prepareApiServer`
 
 - 功能：设置 API 路由的处理函数，在中间件函数中可以拿到 API Server 的前置中间件
 - 执行阶段：请求到达并且 match bff basename 之后执行
@@ -676,11 +665,15 @@ export default (): ServerPlugin => ({
 });
 ```
 
-### Runtime
+## Runtime
+
+:::note
+目前 Runtime 插件还未完全开放，API 不保证稳定，使用需谨慎。
+:::
 
 Runtime 插件主要用于开发者修改需要渲染的组件与 Element 和定制服务器端、客户端的渲染过程。
 
-#### `init`
+### `init`
 
 - 功能：执行 `App.init`
 - 执行阶段：渲染（SSR/CSR）
@@ -703,7 +696,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `hoc`
+### `hoc`
 
 - 功能：修改需要渲染的组件
 - 执行阶段：渲染（SSR/CSR）
@@ -735,7 +728,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `provide`
+### `provide`
 
 - 功能：修改需要渲染的 Element
 - 执行阶段：渲染（SSR/CSR）
@@ -758,7 +751,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `client`
+### `client`
 
 - 功能：定制客户端渲染流程
 - 执行阶段：在浏览器客户端渲染
@@ -784,7 +777,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `server`
+### `server`
 
 - 功能：定制服务器端渲染流程
 - 执行阶段：SSR
@@ -808,89 +801,3 @@ export default (): Plugin => ({
   },
 });
 ```
-
-## 模块工程方案
-
-模块工程方案用于开发可复用模块，主要提供编译构建的能力，插件方面则是主要提供了调整编译构建配置的 Hook。
-
-#### `moduleLessConfig`
-
-- 功能：用于设置 [Less](https://lesscss.org/) 文件的编译配置
-- 执行阶段：`build` 阶段
-- Hook 模型：AsyncPipeline
-- 类型：`AsyncPipeline<{ modernConfig: NormalizedConfig }, LessOption | undefined>`
-- 使用示例：
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  setup(api) {
-    return {
-      moduleLessConfig: ({ modernConfig }) => {
-        // do something
-
-        return {
-          // LESS 配置
-        };
-      },
-    };
-  },
-});
-```
-
-#### `moduleSassConfig`
-
-- 功能：用于设置 [Sass](https://sass-lang.com/) 文件的编译配置
-- 执行阶段：`build` 阶段
-- Hook 模型：AsyncPipeline
-- 类型：`AsyncPipeline<{ modernConfig: NormalizedConfig }, SassOptions | undefined>`
-- 使用示例：
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  setup(api) {
-    return {
-      moduleSassConfig: ({ modernConfig }) => {
-        // do something
-
-        return {
-          // SASS 配置
-        };
-      },
-    };
-  },
-});
-```
-
-#### `moduleTailwindConfig`
-
-- 功能：用于设置 [Tailwind CSS](https://tailwindcss.com/) 的相关配置
-- 执行阶段：`build` 阶段
-- Hook 模型：AsyncPipeline
-- 类型：`AsyncPipeline<{ modernConfig: NormalizedConfig }, any>`
-- 使用示例：
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  setup(api) {
-    return {
-      moduleTailwindConfig: ({ modernConfig }) => {
-        // do something
-
-        return {
-          // Tailwind CSS 配置
-        };
-      },
-    };
-  },
-});
-```
-
-## Monorepo 工程方案
-
-Monorepo 工程方案中目前没有设置额外的插件 Hook，可以创建、添加拥有基础 Hook 的插件：[基础](#基础)。

package/zh/{apis/app/runtime/plugin → guides/topic-detail/framework-plugin}/hook.md

@@ -1,9 +1,8 @@
 ---
+title: Hook 模型
 sidebar_position: 2
 ---
 
-# Hook 模型
-
 首先介绍一下 Modern.js 的基础的插件系统中的一些内容，包括 Hook 模型的工作方式、各个 Hook 模型的运行模式、Manager 的工作模式。
 
 每种 Hook 模型都是独立的，可以独立管理运行函数。
@@ -167,4 +166,4 @@ workflow.run(5) // [6, 10]
 </div>
 </div>
 
-Workflow、Waterfall 其实都是 Pipeline 的变体，Pipeline 可以通过特定的写法来实现 Workflow、Waterfall ，但都较为麻烦，有许多隐形的约定，为了方便使用，提供了这两种变体来满足这种特殊场景。
+Workflow、Waterfall 其实都是 Pipeline 的变体，Pipeline 可以通过特定的写法来实现 Workflow、Waterfall，但都较为麻烦，有许多隐形的约定。为了方便使用，提供了这两种变体来满足这种特殊场景。

package/zh/guides/topic-detail/framework-plugin/implement.md

@@ -1,10 +1,9 @@
 ---
-sidebar_position: 2
+title: 如何编写插件
+sidebar_position: 3
 ---
 
-# 如何编写插件
-
-Modern.js 支持通过自定义插件的方式来实现个性化功能。
+上一小节介绍了 Modern.js 插件的 Hook 模型，这一小节介绍如何编写插件。
 
 ## 实现插件
 
@@ -31,6 +30,8 @@ const MyPlugin = {
 };
 ```
 
+另外，在插件中，允许配置与其他插件的执行顺序，详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
+
 ### 插件类型
 
 使用 TypeScript 时，可以引入内置的 `CliPlugin` 类型，为插件提供正确的类型推导：
@@ -53,9 +54,19 @@ const MyPlugin: CliPlugin = {
 };
 ```
 
-:::info 注
-插件可以注册丰富的 Hooks，不同的 Hook 拥有不同的模型和运行规则，详见 [Hook 模型](/docs/apis/app/runtime/plugin/hook)。
-:::
+Modern.js 导出的 `Plugin` 类型支持泛型扩展。
+
+在 Modern.js 中，任意插件可以注册自己的 Hook，如果想拥有其他插件注册的 Hook 的类型，可以添加泛型：
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+import type { MyPluginHook } from 'xxx';
+
+const MyPlugin: CliPlugin<MyPluginHook> = {};
+```
+
+详细说明，请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
+
 
 ### 插件配置项
 
@@ -79,7 +90,7 @@ const MyPlugin = (options: MyPluginOptions): CliPlugin => ({
 
 ### 插件 API
 
-插件的 setup 函数会接收一个 api 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
+插件的 `setup` 函数会接收一个 api 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
 
 ```ts
 import type { CliPlugin } from '@modern-js/core';
@@ -98,7 +109,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-插件 API 的详细说明，请参考 [Plugin API](/docs/apis/app/runtime/plugin/plugin-api)。
+插件 API 的详细说明，请参考 [Plugin API](/docs/guides/topic-detail/framework-plugin/plugin-api)。
 
 ### 异步 setup
 
@@ -149,7 +160,7 @@ export default defineConfig({
 
 ### 在 npm 上发布插件
 
-如果需要将 Modern.js 插件发布到 npm，推荐使用 Modern.js 中的模块工程方案来管理和构建，如果需要将它和使用项目管理在一起，则推荐使用 Modern.js 中的 Monorepo 工程方案管理。这里就简单地使用模块工程方案进行演示。
+如果需要将 Modern.js 插件发布到 npm，推荐使用 Modern.js 中的模块工程方案来管理和构建。
 
 首先创建一个空的模块工程方案项目，调整 npm 包名称：
 

package/zh/guides/topic-detail/framework-plugin/introduction.md

@@ -0,0 +1,49 @@
+---
+title: 介绍
+sidebar_position: 1
+---
+
+## Modern.js 插件系统
+
+Modern.js 用于扩展项目运行、请求、渲染等不同阶段功能的系统，主要分为三个部分：Hook 模型、管理器，上下文共享机制。
+
+Hook 模型用于确定当前 Hook 的执行方式，不同 Hook 模型的函数拥有不同的执行逻辑。管理器用于控制 Hook 的执行与调度。上下文共享机制用于在不同 Hook 间传递信息。
+
+目前 Modern.js 提供几种不同的 Hook 模型：
+
+- Pipeline
+  - Sync
+  - Async
+- Waterfall
+  - Sync
+  - Async
+- Workflow
+  - Sync
+  - Async
+  - Parallel(Async)
+
+:::note
+后续章节详细介绍各个模型的执行方式。
+:::
+
+基于 Hook 模型和管理器，Modern.js 暴露了三套插件：CLI、Runtime、Server。
+
+其中 CLI 插件是 Modern.js 中主要的运行流程控制模型，Modern.js 中绝大部分功能都是主要通过这一套模型运行的。Runtime 插件主要负责处理 React 组件渲染逻辑。Server 插件主要用于对服务端的生命周期以及用户请求的控制。
+
+## 插件可以做什么
+
+Modern.js 的所有功能都是通过这套插件实现的，这意味着 Modern.js 中的所有能力是都对开发者开放的。开发者可以通过编写插件来扩展更多功能，适配复杂场景，包括但不限于：
+
+- 注册命令
+- 修改 Modern.js 配置、配置校验 Schema
+- 修改编译时的 Webpack/Babel/Less/Sass/Tailwind CSS/... 配置
+- 修改运行时需要渲染的 React 组件、Element
+- 修改页面路由
+- 修改服务器路由
+- 自定义控制台输出
+- 自定义动态 HTML 模版
+- 自定义 Node.js 服务器框架
+- 自定义 React 组件客户端/服务器端渲染
+- ...
+
+当 Modern.js 暂时没有覆盖到你所需要的功能或场景时，可以开发一个自定义插件，来实现适配特殊场景的相关功能。

package/{en/docusaurus-plugin-content-docs/current/apis/app/runtime/plugin → zh/guides/topic-detail/framework-plugin}/plugin-api.md

@@ -1,10 +1,9 @@
 ---
-sidebar_position: 5
+title: 插件 API
+sidebar_position: 6
 ---
 
-# Plugin API
-
-插件的 setup 函数会接收一个 api 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
+插件的 `setup` 函数会接收一个 `api` 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
 
 ```ts
 import type { CliPlugin } from '@modern-js/core';

package/zh/guides/topic-detail/framework-plugin/relationship.md

@@ -1,9 +1,8 @@
 ---
-sidebar_position: 3
+title: 插件之间的关系
+sidebar_position: 4
 ---
 
-# 插件之间的关系
-
 Modern.js 的插件配置对象提供了一系列的字段，用于控制插件顺序、互斥等能力，可用的字段如下：
 
 - `name`: `string`，设置当前插件的名称。

package/zh/guides/topic-detail/model/quick-start.md

@@ -3,6 +3,10 @@ sidebar_position: 1
 title: 快速上手
 ---
 
+import ReduckMigration from '@site-docs/components/reduck-migration.md'
+
+<ReduckMigration />
+
 [Reduck](https://github.com/modern-js-dev/reduck) 是 Modern.js 团队开发的遵循 MVC 模式的状态管理库，底层状态存储基于 [Redux](https://redux.js.org/) 实现，同时提供更高层级的抽象，并完全兼容 Redux 生态。
 
 Reduck 的目标是以 MVC 模式组织 React 应用开发结构，将业务逻辑维护在 Model 层，业务逻辑与 UI 解耦，让开发业务逻辑更集中、更简单，同时通过更高层级的抽象，减少重复工作（样板代码）。
@@ -77,7 +81,7 @@ export default countModel;
 
 接下来，我们演示如何在组件中使用 Model。
 
-新建一个组件 Counter，在组件内通过 `useModel` API 使用 countModel：
+新建一个组件 Counter，在组件内通过 `useModel` API 使用 `countModel`：
 
 ```js
 import { useModel } from '@modern-js/runtime/model';

package/zh/guides/topic-detail/model/test-model.md

@@ -8,8 +8,8 @@ title: 测试 Model
 使用测试功能，需要先开启该功能。在项目根目录下，执行 `pnpm run new`，进行如下选择：
 
 ```bash
-? 请选择你想要的操作： 启用可选功能
-? 启用可选功能： 启用「单元测试 / 集成测试」功能
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「单元测试 / 集成测试」功能
 ```
 
 即可开启测试功能支持。

package/zh/guides/topic-detail/monorepo/intro.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# 简介
+# Monorepo 工程介绍
 
 Modern.js 提供了对于 Monorepo 工程方案的支持，其主要通过 `@modern-js/monorepo-tools` 来提供功能。
 

package/zh/guides/troubleshooting/dependencies.md

@@ -4,75 +4,6 @@ sidebar_position: 1
 
 # 依赖安装问题
 
-### 如何升级项目中的 Modern.js 到最新版本？
-
-对于使用 yarn 的项目，可以执行：
-
-```bash
-yarn upgrade --scope @modern-js
-```
-
-对于使用 pnpm 的项目，可以执行：
-
-```bash
-pnpm update "@modern-js/*" -r
-```
-
-如果需要了解不同版本之间的更新内容，可以查看：
-
-- Modern.js 发版日志：[Modern.js/releases](https://github.com/modern-js-dev/modern.js/releases)。
-- 各个 package 下的 `CHANGELOG.md` 文件。
-
----
-
-### 如何锁定项目中的某个依赖版本？
-
-如果需要锁定项目中的某个依赖的版本，可以通过以下方式进行操作：
-
-**yarn**
-
-对于使用 yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn`：
-
-```json
-{
-  "resolutions": {
-    "package-name": "^1.0.0"
-  }
-}
-```
-
-**pnpm**
-
-对于使用 pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm i`：
-
-```json
-{
-  "pnpm": {
-    "overrides": {
-      "package-name": "^1.0.0"
-    }
-  }
-}
-```
-
-**npm**
-
-对于使用 npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm i`：
-
-```json
-{
-  "overrides": {
-    "package-name": "^1.0.0"
-  }
-}
-```
-
-:::info
-对于 monorepo 场景，只能在项目根目录的 `package.json` 中锁定依赖版本，并且会影响 monorepo 中的所有 package。
-:::
-
----
-
 ### 如何查看项目里某个依赖实际安装的版本？
 
 可以使用包管理器自带的 `ls` 命令来查看项目里依赖的版本。

package/zh/tutorials/first-app/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "创建第一个应用",
+  "label": "联系人列表应用",
   "position": 2,
   "collapsed": false
 }