@modern-js/main-doc 2.1.0 → 2.2.0

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/hook.md

@@ -1,172 +0,0 @@
----
-title: Hook 模型
-sidebar_position: 2
----
-
-首先介绍一下 Modern.js 的基础的插件系统中的一些内容，包括 Hook 模型的工作方式、各个 Hook 模型的运行模式、Manager 的工作模式。
-
-每种 Hook 模型都是独立的，可以独立管理运行函数。
-
-## 基础工作方式
-
-先以 Pipeline 为例，简单介绍一下 Hook 模型的工作方式。先看一个简单的例子：
-
-```ts
-import { createPipeline } from '@modern-js/plugin';
-
-// 1. 创建
-const pipeline = createPipeline<number, number>();
-
-// 2. 添加函数
-pipeline.use((count, next) => {
-  return next(count + 1);
-});
-pipeline.use((count, next) => {
-  return count * 2;
-});
-
-// 3. 执行
-pipeline.run(1); // 4
-pipeline.run(5); // 12
-```
-
-在这个例子中，创建了一个 `Pipeline<number, number>` 类型的 Pipeline（L3），这意味着运行它的时候，你需要传入一个 `number`，然后你会得到一个 `number`，而这个模型管理的函数的类型是：
-
-```ts
-(count: number, next: (nextCount: number) => number) => number;
-```
-
-这里全是 `number`，是因为我们创建的是 `Pipeline<number, number>` ，如果创建的是 `Pipeline<number, string>` 则运行它入参是 `number`，返回值是 `string`，对应管理的函数的类型会是：
-
-```ts
-(count: number, next: (nextCount: number) => string) => string;
-```
-
-创建好 Pipeline 之后，可以通过 `use` 添加函数（L5、L8），需要注意的是，添加的顺序就是他们默认的运行顺序，在这些函数中，你可以对 `count` 进行处理、返回一个值，如果你调用了 `next` 函数，则会运行后面的函数，即如果你添加了三个函数： `A`、`B`、`C`，如果你在 `A` 中调用 `next` 那么就会运行 `B`，同样的，如果你在 `B` 中调用 `next` 那么就会运行 `C`，而在上面的例子中，添加的第一个函数（L5）就运行了 `next`，所以这里就会运行第二个函数（L8），并且运行的返回值就是 第二个函数的返回值，如果在第一个函数中没有调用 `next`，直接返回，例如：
-
-```ts
-import { createPipeline } from '@modern-js/plugin';
-
-// 1. 创建
-const pipeline = createPipeline<number, number>();
-
-// 2. 添加函数
-pipeline.use((count, next) => {
-  return count + 1;
-});
-pipeline.use((count, next) => {
-  return count * 2;
-});
-
-// 3. 执行
-pipeline.run(1); // 2
-pipeline.run(5); // 6
-```
-
-则在运行 Pipeline 的时候就不会运行第二个函数，那么 Pipeline 的运行结果则就是第一个函数的返回值。
-
-最后，运行 Pipeline 的方式也显而易见就是调用 `pipeline.run` 。
-
-## 不同 Hook 模型的区别
-
-上面这部分就是 Pipeline 整体的一个工作模式的描述，其他的 Hook 模型的工作模式基本也是这样，主要的区别点，是函数类型、执行顺序，参数。
-
-### Pipeline
-
-上面的例子就是以 Pipeline 为例描述的，这里就不赘述了，在 Pipeline 这个大类中，提供了两个小类：Sync 和 Async，顾名思义，它们的区别就是管理的函数的类型是 Sync 的还是 Async 的。
-
-:::info 注
-当 Pipeline 中没有函数或者所有函数都调用了 `next` 函数，则就需要在运行的时候提供：
-
-```ts
-pipeline(
-  {},
-  {
-    onLast: () => {
-      // do something
-    },
-  },
-);
-```
-
-:::
-
-### Waterfall
-
-这种模型顾名思义，他的特点就是参数的顺序递交，即前面一个函数的返回值，将会成为下一个函数的入参，我们也用一个例子来看一下：
-
-```ts
-import { createWaterfall } from '@modern-js/plugin';
-
-// 1. 创建
-const waterfall = createWaterfall<number>();
-
-// 2. 添加函数
-waterfall.use(count => {
-  return count + 1;
-});
-waterfall.use(count => {
-  return count * 2;
-});
-
-// 3. 执行
-waterfall.run(1); // 4
-waterfall.run(5); // 12
-```
-
-这个例子中，创建了一个类型为 `Waterfall<number> `，即这个模型执行的入参和返回值是一样的，这个例子中都是 `number`，而它管理的函数的类型是：
-
-```ts
-(count: number) => number;
-```
-
-可能简单看这个例子感觉和上面的 Pipeline 功能一样，那需要注意的是，首先这里 Waterfall 管理的函数没有 next 函数作为第二个参数，所以它无法在函数内部通过调用 next 来先运行之后添加的函数，从而修改运行的顺序，其次这里的运行的入参的类型和返回值的类型必须是一样的（而 Pipeline 可以不一样）。
-
-同样的，在 Waterfall 这个大类中，也提供了 Sync 和 Async 的小类，分别对应 Sync 和 Async 的函数。
-
-### Workflow
-
-这种 Hook 模型与上面两种 Hook 模型的区别是，没有那么强的前后参数返回值递交的概念，在这个模型中，每个函数都是基于同样的入参，相对独立运行的，通过一个例子简单看一下：
-
-```ts
-import { createWorkflow } from '@modern-js/plugin';
-
-// 1. 创建
-const workflow = createWorkflow<number, number>();
-
-// 2. 添加函数
-workflow.use(count => {
-  return count + 1;
-});
-workflow.use(count => {
-  return count * 2;
-});
-
-// 3. 执行
-workflow.run(1); // [2, 2]
-workflow.run(5); // [6, 10]
-```
-
-在这个例子中，添加了两个函数，所以运行的结果就是这两个函数运行的结果形成的一个数组。
-
-虽然这种模型中没有那么强的前后参数返回值递交的概念，但依旧有执行顺序的区别，在 Workflow 这个大类中，提供了三个小类：Sync、Async、Parallel。他们之间的区别就是函数的执行顺序，当然默认的都是按照添加顺序执行，而在 Sync、Async 则是强制按照添加顺序执行，而 Parallel 则是 Async 模式的一个变体，即它使用的是 `Promise.all` 来执行所有函数，而 Async 则会 `await` 前面的函数运行结束。
-
-## Hook 模型对比
-
-<div style={{ width: "100%", overflowX: "scroll" }}>
-<div style={{ width: "150%" }}>
-
-|                  | 函数类型   | 执行顺序                                                   | 函数参数来源                                                                               | 执行返回值来源           | 倾向处理的任务类型                                                  | 函数 TS 类型                                           |
-| ---------------- | ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------ |
-| Pipeline         | Sync       | 默认执行第一个添加的函数，可以通过 next 调用之后添加的函数 | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数向 next 函数传递的参数 | 第一个函数的返回值       | <ul><li>需要修改初始参数</li><li>需要修改函数执行顺序</li></ul>     | `(input: I, next: Next<I, O>) => O`                    |
-| AsyncPipeline    | Sync/Async | 默认执行第一个添加的函数，可以通过 next 调用之后添加的函数 | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数向 next 函数传递的参数 | 第一个函数的返回值       | <ul><li>需要修改初始参数</li><li>需要修改函数执行顺序</li></ul>     | `(input: I, next: AsyncNext<I, O>) => O ｜ Promise<O>` |
-| WaterFall        | Sync       | 一直顺序执行                                               | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数的返回值               | 最后一个函数的返回值     | <ul><li>需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>   | `(I: I) => I`                                          |
-| AsyncWaterFall   | Sync/Async | 一直顺序执行                                               | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数的返回值               | 最后一个函数的返回值     | <ul><li>需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>   | `(I: I) => I ｜ Promise<I>`                            |
-| Workflow         | Sync       | 一直顺序执行                                               | 所有函数的入参都是运行的参数                                                               | 所有函数返回值形成的数组 | <ul><li>不需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul> | `(I: I) => O`                                          |
-| AsyncWorkflow    | Sync/Async | 一直顺序执行                                               | 所有函数的入参都是运行的参数                                                               | 所有函数返回值形成的数组 | <ul><li>不需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul> | `(I: I) => O ｜ Promise<O>`                            |
-| ParallelWorkFlow | Sync/Async | 异步执行                                                   | 所有函数的入参都是运行的参数                                                               | 所有函数返回值形成的数组 | <ul><li>不需要修改初始参数</li><li>不关心执行顺序</li></ul>         | `(I: I) => O ｜ Promise<O>`                            |
-
-</div>
-</div>
-
-Workflow、Waterfall 其实都是 Pipeline 的变体，Pipeline 可以通过特定的写法来实现 Workflow、Waterfall，但都较为麻烦，有许多隐形的约定。为了方便使用，提供了这两种变体来满足这种特殊场景。

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/implement.md

@@ -1,247 +0,0 @@
----
-title: 如何编写插件
-sidebar_position: 3
----
-
-上一小节介绍了 Modern.js 插件的 Hook 模型，这一小节介绍如何编写插件。
-
-## 实现插件
-
-Modern.js 插件是一个对象，对象包含以下属性：
-
-- `name`: 插件的名称，唯一标识符。
-- `setup`: 插件初始化函数，只会执行一次。setup 函数可以返回一个 Hooks 对象，Modern.js 会在特定的时机执行这些 Hooks。
-
-```ts
-const myPlugin = {
-  name: 'my-plugin',
-
-  setup() {
-    // 执行一些初始化逻辑
-    const foo = '1';
-
-    // 返回一个 Hooks 对象
-    return {
-      afterBuild: () => {
-        // 在构建完成后执行逻辑
-      },
-    };
-  },
-};
-```
-
-另外，在插件中，允许配置与其他插件的执行顺序。详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
-
-### 插件类型
-
-Modern-js 支持多种工程开发，如应用工程(app-tools), 模块工程(module-tools)等。
-
-为了兼顾不同工程开发的差异和通性，Modern-js 将插件如下图进行组织:
-
-![plugin-relationship](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/modern-website/plugin-relationship.jpg)
-
-从图可以看出，Modern-js 将插件大致分为两类:
-
-1. 通用插件: 插件只会包含一些基础的 Hooks
-
-2. 工程插件: 不同的工程开发会在通用插件的基础上扩展出自己的 Hooks, Config 等类型。
-
-使用 TypeScript 时，可以引入内置的 `CliPlugin` 等类型，为插件提供正确的类型推导。
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-const myPlugin: CliPlugin = {
-  name: 'my-plugin',
-
-  setup() {
-    const foo = '1';
-
-    return {
-      afterBuild: () => {
-        // 在构建完成后执行逻辑
-      },
-    };
-  },
-};
-```
-
-上述代码为通用插件，只包含一些基础的 Hooks。 Modern.js 支持通过泛型对插件的定义进行扩展：
-
-```ts
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-
-const myPlugin: CliPlugin<AppTools> = {
-  name: 'my-plugin',
-
-  setup() {
-    const foo = '1';
-
-    return {
-      afterBuild: () => {
-        // 在构建完成后执行逻辑
-      },
-    };
-  },
-};
-```
-
-如果仔细观察 `AppTools` 这个类型，可以发现 `AppTools` 由 3 种类型构成.
-
-```ts
-type AppTools = {
-  hooks: AppToolsHooks;
-  userConfig: AppToolsUserConfig;
-  normalizedConfig: AppToolsNormalizedConfig;
-};
-```
-
-当编写插件时，插件通过泛型扩展在不同的基础上扩展自己的 Hooks 等类型:
-
-```ts
-// 通用插件上扩展
-import type { CliPlugin } from '@modern-js/core';
-import type { MyPluginHook } from 'xxx';
-
-const myPlugin: CliPlugin<{ hooks: MyPluginHook }> = {};
-```
-
-```ts
-// 在 @modern-js/app-tools 基础上扩展
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-import type { MyPluginHook } from 'xxx';
-
-const myPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
-```
-
-详细说明，请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
-
-### 插件配置项
-
-**建议将插件写成函数的形式**，使插件能通过函数入参来接收配置项：
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-type MyPluginOptions = {
-  foo: string;
-};
-
-const myPlugin = (options: MyPluginOptions): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup() {
-    console.log(options.foo);
-  },
-});
-```
-
-### 插件 API
-
-插件的 `setup` 函数会接收一个 api 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup(api) {
-    // 获取应用原始配置
-    const config = api.useConfigContext();
-    // 获取应用运行上下文
-    const appContext = api.useAppContext();
-    // 获取解析之后的最终配置
-    const resolvedConfig = api.useResolvedConfigContext();
-  },
-});
-```
-
-插件 API 的详细说明，请参考 [Plugin API](/docs/guides/topic-detail/framework-plugin/plugin-api)。
-
-### 异步 setup
-
-CLI 插件的 setup 可以是一个异步函数，在初始化过程中执行异步逻辑。
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-
-  async setup(api) {
-    await doSomething();
-  },
-});
-```
-
-## 添加插件
-
-自定义插件的使用方式可以查看：[plugins (框架插件)](/docs/configure/app/plugins)。下面会介绍 Modern.js 中推荐的插件实现方法。
-
-### 开发本地插件
-
-本地插件推荐写在 `config/plugin` 目录下，并通过 `export default` 导出：
-
-```ts title=config/plugin/myPlugin.ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup() {
-    // 插件初始化
-  },
-});
-```
-
-然后在 `modern.config.ts` 中注册对应的插件：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import myPlugin from './config/plugin/myPlugin';
-
-export default defineConfig({
-  plugins: [myPlugin()],
-});
-```
-
-### 在 npm 上发布插件
-
-如果需要将 Modern.js 插件发布到 npm，推荐使用 Modern.js 中的模块工程方案来管理和构建。
-
-首先创建一个空的模块工程方案项目，调整 npm 包名称：
-
-```json
-{
-  "name": "my-plugin"
-  ...
-}
-```
-
-然后新建对应的插件文件：
-
-```ts title=src/index.ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup() {
-    // 插件初始化
-  },
-});
-```
-
-发布之后，安装到需要使用的项目 `pnpm add my-plugin`，这里以一个应用项目为例，然后在 `modern.config.ts` 中添加：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import myPlugin from 'my-plugin';
-
-export default defineConfig({
-  plugins: [myPlugin()],
-});
-```
-
-如果你发现目前 Modern.js 存在无法满足的场景，欢迎通过**编写自定义插件的方式**来一起建设 Modern.js 生态。

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/introduction.md

@@ -1,49 +0,0 @@
----
-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/guides/topic-detail/framework-plugin/lifecycle.md

@@ -1,14 +0,0 @@
----
-title: Lifecycle
-sidebar_position: 1
----
-
-Modern.js application has a complete lifecycle, including CLI, Server Side and Runtime three stages.
-
-Modern.js lifecycle is as follows:
-
-:::note
-The rectangle of the pink box represents the plugin hook provided by the Modern.js, and the light yellow base color ellipse represents the linkage point with the next stage.
-:::
-
-![lifecycle](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/life-cycle.svg)

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/plugin-api.md

@@ -1,116 +0,0 @@
----
-title: 插件 API
-sidebar_position: 6
----
-
-插件的 `setup` 函数会接收一个 `api` 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup(api) {
-    // 获取应用原始配置
-    const config = api.useConfigContext();
-    // 获取应用运行上下文
-    const appContext = api.useAppContext();
-    // 获取解析之后的最终配置
-    const resolvedConfig = api.useResolvedConfigContext();
-  },
-});
-```
-
-## API
-
-### useConfigContext
-
-用于获取应用原始配置。
-
-```ts
-const useConfigContext: () => UserConfig;
-
-interface UserConfig {
-  source?: SourceConfig;
-  output?: OutputConfig;
-  server?: ServerConfig;
-  dev?: DevConfig;
-  deploy?: DeployConfig;
-  tools?: ToolsConfig;
-  plugins?: PluginConfig;
-  runtime?: RuntimeConfig;
-  runtimeByEntries?: RuntimeByEntriesConfig;
-}
-```
-
-具体配置字段的意义请参考【[配置](/docs/configure/app/source/alias)】。
-
-### useAppContext
-
-用于获取应用运行上下文。
-
-```ts
-const useAppContext: () => IAppContext;
-
-interface IAppContext {
-  appDirectory: string;
-  configFile: string | false;
-  ip?: string;
-  port?: number;
-  distDirectory: string;
-  packageName: string;
-  srcDirectory: string;
-  sharedDirectory: string;
-  nodeModulesDirectory: string;
-  internalDirectory: string;
-  plugins: {
-    cli?: any;
-    server?: any;
-  }[];
-  entrypoints: Entrypoint[];
-  serverRoutes: ServerRoute[];
-  htmlTemplates: HtmlTemplates;
-}
-```
-
-### useResolvedConfigContext
-
-用于获取解析之后的最终配置。
-
-```ts
-const useResolvedConfigContext: () => NormalizedConfig;
-
-interface NormalizedConfig {
-  source: NormalizedSourceConfig;
-  output: OutputConfig;
-  server: ServerConfig;
-  dev: DevConfig;
-  deploy: DeployConfig;
-  tools: NormalizedToolsConfig;
-  plugins: PluginConfig;
-  runtime: RuntimeConfig;
-  runtimeByEntries?: RuntimeByEntriesConfig;
-  _raw: UserConfig;
-}
-```
-
-具体配置字段的意义请参考【[配置](/docs/configure/app/source/alias)】。
-
-### useHookRunners
-
-用于获取 Hooks 的执行器，并触发特定的 Hook 执行。
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-
-  async setup(api) {
-    const hookRunners = api.useHookRunners();
-    // 触发 afterBuild Hook
-    await hookRunners.afterBuild();
-  },
-});
-```