@modern-js/main-doc 2.0.0-beta.1 → 2.0.0-beta.3

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/generator/codesmith/api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "API",
+  "position": 5
+}

package/zh/guides/topic-detail/generator/codesmith/api/app.md

@@ -0,0 +1,152 @@
+---
+sidebar_position: 1
+---
+
+# @modern-js/codesmith-api-app
+
+微生成器开发过程中常用 API 的组合封装，包含 fs、git、npm 等其他包的 API 封装，在能满足需求时，推荐使用该 npm 包的 API。
+
+## 使用姿势
+
+```typescript
+import { AppAPI } from '@modern-js/codesmith-api-app';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const appApi = new AppAPI(context, generator);
+  await appApi.runInstall();
+}
+```
+
+- 创建 AppAPI 实例，参数和微生成器函数参数一致，为 context 和 generator，具体介绍请看[微生成器项目组成](/docs/guides/topic-detail/generator/codesmith/structure)。
+- 调用其实例上 API 即可。
+
+## API
+
+### checkEnvironment
+
+检查当前生成器运行环境，检查项为：
+
+1. node 及 node 版本，默认大于 12.22.12，可传递参数执行 node 版本。
+2. 可使用 yarn、pnpm 或者 npm。
+
+参数：
+
+- nodeVersion?: `string` 校验的 node 版本。
+
+### runInstall
+
+安装依赖，可传入安装依赖命令，默认根据 config 中的 `packageManager` 值进行。
+
+参数：
+
+- command?: `string` 安装依赖命令。
+
+### runGitAndInstall
+
+该函数完成以下动作：
+
+1. 校验当前生成器执行目录是否为一个 git 仓库。
+2. 如果不是一个 git 仓库，初始化为一个 git 仓库。
+3. 安装依赖。
+4. 在非 monorepo 项目(判断条件，config 中 `isMonorepoSubProject` 不存在或者为 false)中提交初始 commit，commit 信息为 feat: init，支持自定义。
+
+参数：
+- commitMessage?: `string` 初始化 commit message 信息。
+- installFunc?: `() => Promise<void>` 安装依赖函数。
+
+### forgeTemplate
+
+渲染生成器模板文件。
+
+参数：
+
+- templatePattern: string 模板文件匹配正则，例如： `templates/base-templates/**/*` 。
+- filter?: `(resourceKey: string) => boolean` 过滤函数，参数为 templatePattern 匹配的文件路径，返回 true 表示渲染该文件，返回 false 表示不渲染该文件。
+- rename?: `(resourceKey: string) => string` 重命名函数，参数为 templatePattern 匹配的文件路径，返回新文件名。默认会替换 resourceKey 开头的 templates 目录和结尾的 .handlebars 后缀。
+- parameters?: `Record<string, any>` 渲染参数，当模板中存在 handlebars 或者 ejs 变量时，使用其传递对应变量值。
+- type?: `'handlebars' | 'ejs'`  模板文件类型，默认为 handlebars。
+
+例如:
+
+```typescript
+await appApi.forgeTemplate(
+    'templates/base-templates/**/*',
+    undefined,
+    resourceKey =>
+      resourceKey
+        .replace('templates/base-templates/', '')
+        .replace('.handlebars', ''),
+  );
+
+ await appApi.forgeTemplate(
+    'templates/base-template/**/*',
+    resourceKey => !resourceKey.include('eslintrc.json'),
+    resourceKey =>
+      resourceKey
+        .replace('templates/base-template/', projectPath)
+        .replace('language', language as string)
+        .replace('.handlebars', ''),
+    {
+      name: packageName as string,
+      language,
+      isTs: language === Language.TS,
+      packageManager: getPackageManagerText(packageManager as any),
+    },
+  );
+```
+
+### showSuccessInfo
+
+展示成功信息。
+
+参数：
+
+- successInfo?: `string`，默认为 Success || 成功。
+
+### runSubGenerator
+
+运行子生成器。
+
+参数：
+
+- subGenerator: `string` 子生成器名称或者路径。
+- relativePwdPath?: `string` 子生成器运行的相对路径。
+- config?: `Record<string, unknown>` 子生成器运行的默认 config 配置。
+
+例如：
+
+```typescript
+  await appApi.runSubGenerator(
+    getGeneratorPath('@modern-js/repo-generator', context.config.distTag),
+    undefined,
+    { ...context.config, hasPlugin: false },
+  );
+```
+
+### getInputBySchema
+
+通过 schema 完成用户交互输入。
+
+参数：
+
+- schema: `FormilySchema | Question[]` 问题列表，支持 Formily schema 和 inquirer 类型。
+- type: `'formily' | 'inquirer'` 类型，默认值为 formily。
+- configValue: `Record<string, unknown> = {}`  schema 默认值，传入该值的 schema 字段对应的问题将不再和用户交互。
+- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>` schema 中特殊字段的验证函数。
+- initValue?: `Record<string, any>` schema 中字段的初始化值。
+
+Formily Schema 类型支持方式可参考[自定义输入相关类型定义](/docs/guides/topic-detail/generator/plugin/api/input/type)。
+
+### getInputBySchemaFunc
+
+通过 schema 完成用户交互输入，schema 参数值为函数，用户处理国际化问题，仅支持 Formily schema。
+
+
+参数：
+
+- schema: `config?: Record<string, any>) => FormilySchema` 获取问题列表函数，config 参数为当前生成器中的 config 配置信息。
+- configValue: `Record<string, unknown> = {}`  schema 默认值，传入该值的 schema 字段对应的问题将不再和用户交互。
+- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>` schema 中特殊字段的验证函数。
+- initValue?: `Record<string, any>` schema 中字段的初始化值。
+
+Formily Schema 类型支持方式可参考[自定义输入相关类型定义](/docs/guides/topic-detail/generator/plugin/api/input/type)。

package/zh/guides/topic-detail/generator/codesmith/api/ejs.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 6
+---
+
+# @modern-js/codesmith-api-ejs
+
+微生成器中使用 [ejs](https://ejs.co/) 进行文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。
+
+## 使用姿势
+
+```typescript
+import { EjsAPI } from '@modern-js/codesmith-api-ejs';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const ejsAPI = new EjsAPI(generator);
+  await ejsAPI.renderTemplate(
+     material.get('templates/a.js'),
+     target: 'b.js',
+     { data: "data" }
+   );
+}
+```
+
+- 创建 EjsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### renderTemplate
+
+渲染单个模板文件。
+
+参数：
+
+- templateResource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
+- target: `string` 目标文件路径名称。
+- parameters?: `Record<string, string>` 渲染参数。
+
+### renderTemplateDir
+
+渲染模板文件夹。
+
+参数：
+
+- material: `FsMaterial` 当前微生成器执行的 material 上下文。
+- findGlob: `string` 模板文件匹配正则。
+- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
+- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
+
+```typescript
+type RenderTemplateDirOptions = {
+  nodir?: boolean;
+  dot?: boolean;
+  ignore?: string | readonly string[];
+};
+```

package/zh/guides/topic-detail/generator/codesmith/api/fs.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 3
+---
+
+# @modern-js/codesmith-api-fs
+
+微生成器中文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。FsAPI 通常用于处理二进制文件或者不能使用 handlebars、ejs 处理的模板文件。
+
+## 使用姿势
+
+```typescript
+import { FsAPI } from '@modern-js/codesmith-api-fs';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const handlebarApi = new HandlebarsAPI(generator);
+  await handlebarsAPI.renderFile(
+     material.get('templates/a.js'),
+     target: 'b.js'
+   );
+}
+```
+
+- 创建 FsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### renderFile
+
+渲染单个模板文件。
+
+参数：
+
+- resource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
+- target: `string` 目标文件路径名称。
+
+### renderDir
+
+渲染模板文件夹。
+
+参数：
+
+- material: `FsMaterial` 当前微生成器执行的 material 上下文。
+- findGlob: `string` 模板文件匹配正则。
+- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
+- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
+
+```typescript
+type RenderTemplateDirOptions = {
+  nodir?: boolean;
+  dot?: boolean;
+  ignore?: string | readonly string[];
+};
+```

package/zh/guides/topic-detail/generator/codesmith/api/git.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 4
+---
+
+# @modern-js/codesmith-api-git
+
+微生成器中使用 git 相关操作的 API 封装，提供判断 git 仓库，初始化及提交代码等方法。
+
+## 使用姿势
+
+```typescript
+import { GitAPI } from '@modern-js/codesmith-api-git';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const gitApi = new GitAPI(generatorCore, generatorContext);
+  await gitApi.initGitRepo();
+}
+```
+
+- 创建 GitAPI 实例，参数和微生成器函数参数一致，为 context 和 generator，具体介绍请看微生成器项目组成
+- 调用其实例上 API 即可。
+
+## API
+
+### isInGitRepo
+
+当前目录是否为 git 仓库。
+
+参数：
+
+- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。
+
+### initGitRepo
+
+初始化为 git 仓库。init 的默认分支名可通过生成器 config 中的 defaultBranch 进行配置。
+
+参数：
+
+- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。
+- force?: `boolean` 当前目录已经为 git 仓库时使用该参数会强制执行 git init。
+
+### addAndCommit
+
+执行 `git add .` 和 `git commit` 提交当前变更。
+
+参数：
+- commitMessage: `string` commit 信息。
+- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。

package/zh/guides/topic-detail/generator/codesmith/api/handlebars.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 5
+---
+
+# @modern-js/codesmith-api-handlebars
+
+微生成器中使用 [handlebars](https://handlebarsjs.com/) 进行文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。
+
+## 使用姿势
+
+```typescript
+import { HandlebarsAPI } from '@modern-js/codesmith-api-handlebars';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const handlebarApi = new HandlebarsAPI(generator);
+  await handlebarsAPI.renderTemplate(
+     material.get('templates/a.js'),
+     target: 'b.js',
+     { data: "data" }
+   );
+}
+```
+
+- 创建 HandlebarsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### renderTemplate
+
+渲染单个模板文件。
+
+参数：
+
+- templateResource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
+- target: `string` 目标文件路径名称。
+- parameters?: `Record<string, string>` 渲染参数。
+
+### renderTemplateDir
+
+渲染模板文件夹。
+
+参数：
+
+- material: `FsMaterial` 当前微生成器执行的 material 上下文。
+- findGlob: `string` 模板文件匹配正则。
+- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
+- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
+
+```typescript
+type RenderTemplateDirOptions = {
+  nodir?: boolean;
+  dot?: boolean;
+  ignore?: string | readonly string[];
+};
+```

package/zh/guides/topic-detail/generator/codesmith/api/json.md

@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+---
+
+# @modern-js/codesmith-api-json
+
+微生成器中 JSON API 封装，提供常见的 JSON 文件操作方法。
+
+## 使用姿势
+
+```typescript
+import { JsonAPI } from '@modern-js/codesmith-api-json';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const jsonAPI = new JsonAPI(generator);
+  await jsonAPI.update(
+    context.materials.default.get('package.json'),
+    {
+      query: {},
+      update: {
+        $set: {
+          'dependencies.@modern-js/plugin-bff': `^2.0.0`,
+        },
+      },
+    },
+  );
+ }
+```
+
+- 创建 JsonAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看[微生成器项目组成](/docs/guides/topic-detail/generator/codesmith/structure)。
+- 调用其实例上 API 即可。
+
+## API
+
+### get
+
+获取 JSON 文件内容。
+
+参数：
+- resource: `FsResource`，文件资源，通过 `context.materials.default.get(<filename>)` 获取。
+
+### extend
+
+合并对象至 JSON 文件。
+
+参数：
+
+- resource: `FsResource` 通过 `context.materials.default.get(<filename>)` 获取。
+- obj: `Record<string, any>` 需合并对象。
+
+### update
+
+更新对象字段至 JSON 文件。
+
+参数：
+
+- resource: `FsResource` 通过 `context.materials.default.get(<filename>)` 获取。
+- operation: `{ query: Record<string, any>; update: Record<string, any> }` 更新操作，详细使用姿势查看 [declaration-update](https://www.npmjs.com/package/declaration-update)。

package/zh/guides/topic-detail/generator/codesmith/api/npm.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 7
+---
+
+# @modern-js/codesmith-api-npm
+
+微生成器中 NPM API 封装，提供常见的 NPM 不同包管理工具安装依赖的方法。
+
+## 使用姿势
+
+```typescript
+import { NpmAPI } from '@modern-js/codesmith-api-npm';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const npmApi = new NpmAPI(generator);
+  await npmApi.pnpmInstall();
+}
+```
+
+- 创建 NpmAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### npmInstall
+
+使用 npm 安装依赖。
+
+参数：
+
+- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。
+
+### yarnInstall
+
+使用 yarn 安装依赖。
+
+参数：
+- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。
+
+### pnpmInstall
+
+使用 pnpm 安装依赖。
+
+参数：
+- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。

package/zh/guides/topic-detail/generator/codesmith/develop.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+---
+
+# 开发微生成器项目
+
+## 创建项目
+
+Modern.js 提供了创建微生成器项目的微生成器，可以直接通过以下命令创建微生成器项目：
+
+```bash
+$ mkdir <projectDir>
+$ npx @modern-js/codesmith-cli @modern-js/generator-generator
+
+? 请填写项目名称 <generatorName>
+? 请选择包管理工具 pnpm
+? 请选择开发语言 TS
+```
+
+## 添加模板文件
+
+在项目目录的 templates 文件夹，用于存放生成器需要的模板文件，如果没有模板文件，该步骤可跳过。
+
+## 开发生成器核心逻辑
+
+默认生成的的项目中，已经实现直接拷贝 templates 目录文件至目标项目，可直接在 `handleTemplateFile` 函数中完成生成器的核心逻辑开发。
+
+## 测试微生成器
+
+微生成器开发完成后，需要执行 `pnpm run build` 对代码进行编译，在开发模式下可以使用 `pnpm run build --watch`
+
+codesmith 提供了 cli 工具用于运行和测试微生成器，在目标目录执行使用如下命令执行即可：
+
+```bash
+npx @modern-js/codesmith-cli <generatorPath>
+```
+
+其中 generatorPath 为上述生成器项目的绝对路径。
+
+## 运行微生成器
+
+生成器发布 npm 包之后，使用如下命令执行：
+
+```bash
+npx @modern-js/codesmith-cli <generatorName>
+```
+
+其中 generatorName 为生成器包名。
+
+:::info
+`@modern-js/create` 也支持运行微生成器，可以使用 `npx @modern-js/create --generator <generatorName>` 运行自定义的微生成器。
+:::