@modern-js/main-doc 2.21.1 → 2.22.1

package/docs/zh/guides/topic-detail/generator/plugin/api/context.md

@@ -0,0 +1,184 @@
+---
+sidebar_position: 1
+---
+
+# context
+
+生成器插件在 `main` 文件中默认导出了一个函数，函数参数为 `context`，生成器插件提供的所有 API 都是由这个 `context` 提供的。
+
+## 类型
+
+我们先大概了解一下 `context` 的类型定义：
+
+```ts
+export interface IPluginContext {
+  locale?: string;
+  addInputBefore: (key: string, input: Schema) => void;
+  addInputAfter: (key: string, input: Schema) => void;
+  setInput: (key: string, field: string, value: unknown) => void;
+  setInputValue: (value: Record<string, unknown>) => void;
+  setDefaultConfig: (value: Record<string, unknown>) => void;
+  isFileExist: (fileName: string) => Promise<boolean>;
+  readDir: (dir: string) => Promise<string[]>;
+  setGitMessage: (gitMessage: string) => void;
+  onForged: (func: PluginForgedFunc) => void;
+  afterForged: (func: PluginAfterForgedFunc) => void;
+}
+```
+
+`context` 提供的内容主要分为三类：
+
+- 获取当前生成器执行环境信息
+
+- 操作 input 输入
+
+- 生成器插件生命周期函数
+
+下面将从这三个分类分别介绍生成器插件 API。
+
+
+### 获取信息
+
+#### locale
+
+获取生成器插件执行环境的语言。`@modern-js/create` 提供了 `zh` 和 `en` 两种语言，这里即为对应的这两种值。
+
+#### isFileExist
+
+判断文件是否存在。我们很多时候需要在定义操作前确认目标项目文件是否已经存在，可以直接通过该 API 获取。
+
+例如我们需要获取 `package.json` 文件是否存在，然后做相应的操作：
+
+```ts
+const isExist = await context.isFileExist('package.json');
+if (isExist) {
+    ...
+}
+```
+
+#### readDir
+
+获取文件夹内文件列表。我们很多时候需要在定义操作前获取目标项目文件夹下面文件列表，可以直接通过该 API 获取。
+
+例如我们需要获取 src 文件夹下所有文件，然后进行相应操作：
+
+```ts
+const files = await context.readDir('src');
+
+files.map(name => {
+    ...
+});
+```
+
+### input 操作
+
+input 操作中使用的 key 参数可参考[配置参数](/guides/topic-detail/generator/create/config.html)，需要在使用对应工程方案下的 key，即不支持在 `solution` 和 `scenes`。
+
+input 操作中的 input 参数对应的 Schema 类型可参考 [Input](/guides/topic-detail/generator/plugin/api/input.html)。
+
+#### addInputBefore
+
+在指定的 input `key` 前添加问题。
+
+例如：
+
+```ts
+context.addInputBefore('packageManager', {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: '开发语言',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+});
+```
+
+#### addInputAfter
+
+在指定的 input `key` 后添加问题。
+
+例如：
+
+```ts
+context.addInputAfter('packageManager', {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: '开发语言',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+});
+```
+
+:::info
+1. 添加问题的 `key` 不能和 Modern.js 提供的工程方案自身的问题的 `key` 重复。
+2. 添加问题 `addInputAfter` 的优先级高于 `addInputBefore`，当同时对一个 key 添加 After 问题和对其后一个key 添加 Before 问题时，After 问题会在 Before 之前。
+3. 当需要在相同 `key` 前面或者后面添加多个问题时，可多次调用该方法，问题的顺序会按照调用顺序进行排列。
+
+:::
+
+#### setInput
+
+设置指定 input `key` 的属性。
+
+例如设置 `packageName` 的 `title` 属性：
+
+```ts
+context.setInput('packageName', 'title', "展示名称");
+```
+
+:::info
+对于 Modern.js 工程方案提供的输入选项，只支持删除，不支持增加，增加会造成代码中的逻辑判断存在问题。
+:::
+
+
+#### setInputValue
+
+设置指定 input `key` 的选项默认值。
+
+例如设置 `packageManager` 的默认值：
+
+```ts
+context.setInputValue({
+  packageManager: 'npm',
+});
+```
+
+:::info
+设置完成后，该问题还是需要交互，只是会使用生成器插件配置的默认值。
+:::
+
+#### setDefaultConfig
+
+设置指定 input `key` 的默认值。
+
+例如设置 `packageManager` 的默认值：
+
+```ts
+context.setDefaultConfig({
+  packageManager: 'npm',
+});
+```
+
+:::info
+设置完成后，将不再展示对应问题，和 `@modern-js/create` 制定 `--config` 行为一致。不支持设置 `vertical` 和 `projectOrg`。
+:::
+
+#### setGitMessage
+
+设置 Git 初始提交信息。Modern.js 默认 Git 初始化提交信息为 `feat: init`，通过该函数可以修改。
+
+
+### 生命周期函数
+
+生命周期函数比较复杂，将通过后面两节 [`onForged`](/guides/topic-detail/generator/plugin/api/onForged.html) 和 [`afterForged`](/guides/topic-detail/generator/plugin/api/afterForged.html) 分别介绍。

package/docs/zh/guides/topic-detail/generator/plugin/api/input.md

@@ -0,0 +1,124 @@
+---
+sidebar_position: 4
+---
+
+# Input
+
+生成器插件提供了 Input 的方式完成与用户的问题交互，使用 JSON Schema 的方式进行定义：
+
+例如：
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: '开发语言',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+};
+```
+
+JSON Schema 的格式参考了开源的 [Formily](https://formilyjs.org/) Schema 的格式，下面将对支持的字段进行介绍：
+
+## type
+
+定义当前 Schema 类型，当前支持的类型为 `string`、`number` 和 `object`。字符串输入和下拉选项都需要使用 `string` 类型。 `object` 类型用于实现 Schema 之间嵌套，需要配和 `properties` 属性使用。
+
+## title
+
+定义当前 Schema 展示名称。
+
+## default
+
+定义当前 Schema 的默认值。
+
+## enum
+
+当前 Schema 为下列选项时，定义选项内容。
+
+子项支持 `string` 或者 `{ label: string; value: string}` 类型，当下拉选项中值和展示值相同时，可直接使用 `string` 定义。
+
+当需要表示多选选项时，设置 `default` 字段为 `[]` 即可。
+
+## x-validator
+
+当前 Schema 的校验规则。当 Schema 为输入类型时，在输入完成后会自动完成校验。
+
+这里校验规则支持[ Formily 提供的校验规则](https://formilyjs.org/zh-CN/guide/advanced/validate)，例如最大值为 5：
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    max_5: {
+      type: 'number',
+      title: '最大值(>5报错)',
+      'x-validator': {
+        maximum: 5,
+      },
+    },
+  },
+};
+```
+
+也支持直接使用验证函数：
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      title: '只能包含数字和字母',
+      'x-validator': value => {
+        if (!/^[0-9a-zA-Z]*$/g.test(value)) {
+          return '格式不正确';
+        }
+        return '';
+      },
+    },
+  },
+};
+```
+
+## x-reactions
+
+使用 Schema 之间的联动，这里和[ Formily 联动规则](https://formilyjs.org/zh-CN/guide/advanced/linkages)完全相同。
+
+例如：
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      title: '名称',
+    },
+    path: {
+      type: 'string',
+      title: '路径',
+      'x-reactions': [
+        {
+          dependencies: ['name'],
+          fulfill: {
+            state: {
+              value: '{{$deps[0]}}',
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+```
+
+## properties
+
+组织当前 Schema 的结构，定义子表单。`properties` 为对象，`key` 为 Schema 关键字，`value` 为上述描述的 Schema 对象。

package/docs/zh/guides/topic-detail/generator/plugin/api/onForged.md

@@ -0,0 +1,310 @@
+---
+sidebar_position: 2
+---
+
+# onForged
+
+`onForged` 为生成器插件中用于文件操作的生命周期函数。
+
+## 类型
+
+```ts
+export type ForgedAPI = {
+  addFile: (params: AddFileParams) => Promise<void>;
+  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
+  updateJSONFile: (fileName: string, updateInfo: Record<string, unknown>) => Promise<void>;
+  updateTextRawFile: (fileName: string, update: (content: string[]) => string[]) => Promise<void>;
+  updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
+  rmFile: (fileName: string) => Promise<void>;
+  rmDir: (dirName: string) => Promise<void>;
+  addHelper: (name: string, fn: Handlebars.HelperDelegate) => void;
+  addPartial: (name: string, str: Handlebars.Template) => void;
+  createElement: (element: ActionElement, params: Record<string, unknown>) => Promise<void>;
+  enableFunc: (func: ActionFunction, params?: Record<string, unknown> | undefined) => Promise<void>;
+};
+
+export type PluginForgedFunc = (
+  api: ForgedAPI,
+  inputData: Record<string, unknown>,
+) => void | Promise<void>;
+
+export interface IPluginContext {
+  onForged: (func: PluginForgedFunc) => void;
+  ...
+}
+```
+
+`onForged` 参数为一个回调函数，回调函数参数为 `api` 和 `input`，分别用于提供该生命周期函数提供的 API 及当前输入信息。
+
+## 概念
+
+### 文件类型
+
+生成器插件将文件类型分为撕四类：
+
+- 文本文件
+
+纯文本内容文件，可使用 [Handlebars](https://handlebarsjs.com/) 或 [EJS](https://ejs.co/) 进行模板处理的文件。
+
+- 二进制文件
+
+图片、音频、视频等文件。
+
+- JSON 文件
+
+JSON 格式的文件。
+
+- 文本列表文件
+
+文件由行文本组成的文件，例如 `.gitignore`, `.editorconfig`, `.npmrc`。
+
+对应四种文件的类型定义为：
+
+```ts
+export enum FileType {
+  Text = 'text',
+  Binary = 'binary',
+  Json = 'json',
+  TextRaw = 'textRaw',
+}
+```
+
+## API
+
+下面将分别介绍 api 参数提供的 API。
+
+### addFile
+
+添加单个文件。
+
+参数类型：
+
+```ts
+export interface AddFileParams {
+  type: FileType;
+  file: string;
+  template?: string;
+  templateFile?: string;
+  force?: boolean;
+  data?: Record<string, string>;
+}
+```
+
+- `type`： 文件类型。
+- `file`：目标文件路径，相对于目标项目目录的相对路径。
+- `template`：模板内容，该字段值可直接用于模板渲染文件。优先级低于 `templateFile`。
+- `templateFile`：模板文件路径，相对于 templates 目录的相对路径即可。
+- `force`：是否强制覆盖，当目标文件存在时是否强制覆盖，默认为 false。
+- `data`：模板渲染数据。
+
+:::info
+文本类型文件默认使用 Handlebars 进行处理，当模板文件以 `.ejs` 结尾的话，会使用 [EJS](https://ejs.co/) 进行模板渲染。
+:::
+
+例如添加模板文件 `App.tsx.hanlebars` 到 `src/App.tsx` 中:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.addFile({
+    type: FileType.Text,
+    file: `src/App.tsx`,
+    templateFile: `App.tsx.handlebars`,
+  });
+})
+```
+
+### addManyFiless
+
+批量添加文件，一般用于添加多个文件到同一个目标目录。
+
+参数类型：
+
+```ts
+export interface AddManyFilesParams {
+  type: FileType;
+  destination: string;
+  templateFiles: string[] | (() => string[]);
+  templateBase?: string;
+  fileNameFunc?: (name: string) => string;
+  data?: Record<string, string>;
+}
+```
+
+- `type`： 文件类型。
+- `destination`：目标文件夹，相对于目标项目目录的相对路径。
+- `templateFiles`：模板文件列表，支持 [globby](https://www.npmjs.com/package/globby) 正则表达式
+- `templateBase`：模板文件的公共路径，使用该参数时目标文件会自动删除该路径。
+- `fileNameFunc`：重命名文件函数，添加文件过程中会依次将文件名传入到该函数，可以根据需要进行重命名。
+- `data`：模板渲染数据。
+
+例如将模板文件 `src-ts` 目录下所有文件渲染到 `src` 目录：
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.addManyFiles({
+    type: FileType.Text,
+    destination: 'src',
+    templateFiles: ['src-ts/**/*'],
+    templateBase: 'src-ts',
+    fileNameFunc: name => name.replace('.handlebars', ''),
+  });
+})
+```
+
+### updateJSONFile
+
+更新 JSON 文件字段。
+
+参数类型：
+
+```ts
+fileName: strings
+updateInfo: Record<string, unknown>
+```
+
+- `fileName`：JSON 文件路径，相对于目标项目的路径。
+- `updateInfo`：更新信息，嵌套字段更新需要平铺，不然会更新整体造成内容丢失。
+
+例如更新 `package.json` 的 name 字段：
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateJSONFile('package.json', { name: 'new_name' });
+})
+```
+
+例如更新 `dependencies` 的 `react-dom` 版本:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateJSONFile('package.json', {
+    'dependencies.react-dom': '^18',
+  });
+})
+```
+
+### updateTextRawFile
+
+更新文本列表文件内容。
+
+参数类型：
+
+```ts
+fileName: string
+update: (content: string[]) => string[]
+```
+
+- `fileName`： 文本列表文件路径，相对于目标项目的路径。
+- `update`：更新函数，参数为当前文件内容以 `\n` 进行分割的数组，返回值也为修改完成后的数组，`@modern-js/create` 会自动以 `\n` 合并，并写入源文件。
+
+例如 `.gitinore` 文件中增加 dist 目录：
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateTextRawFile('.gitinore', (content) => [...content, 'dist']);
+})
+```
+
+### updateModernConfig(不推荐)
+
+Modern.js 配置除了可以在 `modern.config.[tj]s` 中配置外，还支持 `package.json` 中配置 `modernConfig` 配置。该函数用于更新该字段。
+
+参数类型：
+
+```ts
+updateInfo: Record<string, any>
+```
+
+- `updateInfo`： 更新内容信息。updateModernConfig 是基于 updateJSONFile 的封装，将自动更新到 `modernConfig` 字段下，updateInfo 中只需填写 `modernConfig` 下的配置字段即可。
+
+例如开启 ssr：
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateModernConfig({ 'server.ssr': true });
+})
+```
+
+### rmFile
+
+删除文件。
+
+参数类型：
+
+```ts
+fileName: string
+```
+
+- `fileName`：删除的文件路径，相对于目标项目的路径。
+
+### rmDir
+
+删除文件夹。
+
+参数类型：
+
+```ts
+dirName: string
+```
+
+- `dirName`：删除的文件夹路径，相对于目标项目的路径。
+
+### addHelper
+
+添加 handlebrs 渲染的[自定义 Helper](https://handlebarsjs.com/guide/#custom-helpers)。
+
+参数类型：
+
+```ts
+name: string
+fn: Handlebars.HelperDelegate
+```
+
+- `name`：Helper 函数名称。
+- `fn`：Helper 函数实现。
+
+### addPartial
+
+添加 Handlebars 渲染的 [Partial](https://handlebarsjs.com/guide/partials.html#basic-partials)。
+
+参数类型：
+
+```ts
+name: string
+str: Handlebars.Template
+```
+
+- `name`：Partial 名称。
+- `str`：Partial 的模板字符串。
+
+### createElement
+
+自动调用 new 命令创建工程元素。
+
+参数类型：
+
+```ts
+element: ActionElement
+params: Record<string, unknown>
+```
+
+- `element`：工程元素类型，新建入口或者新建自定义 Web Server 源码目录。
+- `params`：对应创建工程元素的其他参数。
+
+### enableFunc
+
+自动调用 new 命令开启可选功能。
+
+参数类型：
+
+```ts
+func: ActionFunction
+params?: Record<string, unknown>
+```
+
+- `func`：开启功能名称。
+- `params`：对应开启功能的其他参数。
+
+:::info
+创建工程元素和开启功能配置可参考[配置参数](/guides/topic-detail/generator/new/config.html)。
+:::

package/docs/zh/guides/topic-detail/generator/plugin/category.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 2
+---
+
+# 类型
+
+## 介绍
+
+生成器插件分为两类：
+
+- 扩展：Web 应用( Npm 模块) = Web 应用( Npm 模块) + 生成器插件
+
+- 自定义：新应用(模块) = Web 应用(模块) + 生成器插件
+
+
+简单理解就是扩展还是使用 Modern.js 原本的工程方案名称，自定义会创建一个新的名称。
+
+## 标识
+
+生成器插件的类型通过 `package.json` 中的 meta 字段来提供：
+
+### 扩展
+
+```json title="package.json"
+{
+ "meta": {
+    "extend": "mwa" // module
+ }
+}
+```
+
+### 自定义
+
+```json title="package.json"
+{
+ "meta": {
+    "key": "new_app",
+    "name": "新应用",
+    "type": "mwa" // module 和 custom
+ }
+}
+```
+
+:::info
+自定义类型的 type 支持 custom 类型，custom 为使用 Modern.js 提供的一些项目开发的最佳实践模板，比如 `.gitignore`、`.editorConfig` 等文件，其他业务相关代码模板需要手动通过生成器插件提供。
+:::
+
+## 创建初始项目
+
+### 扩展
+
+```bash
+npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
+? 请选择你想创建的工程类型 Npm 模块
+? 请选择项目场景 生成器插件
+? 请输入生成器插件插件包名 plugin
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 请选择插件类型 extend
+? 请选择插件基础类型 Web 应用
+```
+
+### 自定义
+
+```bash
+npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
+? 请选择项目类型 生成器插件
+? 请选择项目组织方式 独立项目
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 请输入生成器插件插件包名 plugin
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 请选择插件类型 custom
+? 请输入插件关键字 new_app
+? 请输入插件展示名称 新应用
+? 请选择插件基础类型 Web 应用
+```
+
+## 执行顺序
+
+生成器插件支持同时使用多个，也就是执行 `@modern-js/create` 时支持多个 `--plugin` 参数。
+
+### 扩展
+
+扩展生成器插件支持在执行时会按照声明的生成器插件参数的顺序，依次执行对应 extend 的工程方案的生命周期函数。
+
+例如存在 A 和 B 两个生成器插件，A 和 B 都是 extend 的 Web 应用工程方案，A 插件声明添加 `a.ts` 文件，B 插件声明添加 `b.ts` 文件，
+执行 `npx @modern-js/create@latest --plugin A --plugin B` 时，选择 Web 应用工程时，会先生成 Web 应用默认的项目文件，然后执行 A 插件创建 `a.ts` 文件，再执行 B 插件，生成 `b.ts` 文件。
+
+### 自定义
+
+自定义生成器插件只支持同一时间运行一个生成器插件，当 `@modern-js/create` 声明 `--plugin` 参数时，会在选择工程方案之后增加选择工程方案场景选项，即为上述 `package.json` 中定义的新 name，选择对应 name 的生成器插件，即会在默认工程方案执行完成后，执行对应的生成器插件逻辑。声明 `--plugin` 参数时，工程方案场景下将会逐一列举出对应的生成器插件名称供选择。