@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/apis/generator/plugin/git/isInGitRepo.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+---
+
+# isInGitRepo
+
+判断当前项目是否为一个 Git 仓库。
+
+其类型定义为：
+
+```ts
+export type AfterForgedAPI = {
+  isInGitRepo: () => Promise<boolean>;
+  ...
+};
+```

package/zh/apis/generator/plugin/hook/_category_.json

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

package/zh/apis/generator/plugin/hook/afterForged.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 2
+---
+
+# AfterForged
+
+afterForged 函数为生成器插件生命周期函数，其通常用于定义安装依赖、Git 等操作，专业些操作将会在 onForged 函数执行完成后进行。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export type PluginAfterForgedFunc = (
+  api: AfterForgedAPI,
+  inputData: Record<string, unknown>,
+) => Promise<void>;
+
+export interface IPluginContext {
+  afterForged: (func: PluginAfterForgedFunc) => void;
+  ...
+}
+```
+
+## func
+
+afterForged 参数是一个回调函数，函数参数为 api 和 inputData。
+
+### api
+
+在 afterForged 生命周期中支持的函数列表，具体可查看[Git API](/docs/apis/generator/plugin/git/isInGitRepo) 和[NPM API](/docs/apis/generator/plugin/npm/install)。
+
+### inputData
+
+当前用户输入，可用于获取用户当前的输入信息及配置信息。

package/zh/apis/generator/plugin/hook/onForged.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 1
+---
+
+# OnForged
+
+onForged 函数为生成器插件生命周期函数，其通常用于定义文件类型操作，这些操作将在 base 的工程方案文件操作完成后进行。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export type PluginForgedFunc = (
+  api: ForgedAPI,
+  inputData: Record<string, unknown>,
+) => void | Promise<void>;
+
+export interface IPluginContext {
+  onForged: (func: PluginForgedFunc) => void;
+  ...
+}
+```
+
+## func
+
+onForged 参数是一个回调函数，函数参数为 api 和 inputData。
+
+### api
+
+在 onForged 生命周期中支持的函数列表，具体可查看[文件操作 API](/docs/apis/generator/plugin/file/introduce) 和[启用功能 API](/docs/apis/generator/plugin/new/introduce)。
+
+### inputData
+
+当前用户输入，可用于获取用户当前的输入信息及配置信息。

package/zh/apis/generator/plugin/info/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "获取信息 API",
+  "position": 4
+}

package/zh/apis/generator/plugin/info/isFileExit.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 2
+---
+
+# isFileExit
+
+判断文件是否存在。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export interface IPluginContext {
+  isFileExit: (fileName: string) => Promise<boolean>;
+  ...
+}
+```
+
+## fileName
+
+需要判断的文件名或者文件路径，基于创建的项目的相对路径即可。

package/zh/apis/generator/plugin/info/locale.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 1
+---
+
+# locale
+
+当前语言。
+
+该变量可直接在 context 上获取。
+
+该字段存在两个值：
+
+- zh: 中文
+
+- en: 英文
+
+生成器插件中可根据该字段调整相关展示字段的值。

package/zh/apis/generator/plugin/info/readDir.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 3
+---
+
+# readDir
+
+读取文件夹，获取文件列表。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export interface IPluginContext {
+  readDir: (dir: string) => Promise<string[]>;
+  ...
+}
+```
+
+## dir
+
+文件夹名称或路径，基于创建的项目的相对路径即可。

package/zh/apis/generator/plugin/input/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "自定义输入 API",
+  "position": 3
+}

package/zh/apis/generator/plugin/input/addInputAfter.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 3
+---
+
+# addInputAfter
+
+在默认输入后添加输入问题。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export interface IPluginContext {
+  addInputAfter: (key: string, input: IInput) => void;
+  ...
+}
+```
+
+## key
+
+Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/docs/configure/generator/introduce)。
+
+## input
+
+需要添加的问题，具体类型定义可查看[自定义输入相关类型定义](/docs/apis/generator/plugin/input/type)。
+
+## 示例
+
+在包管理工具后面添加输入：
+
+```ts
+context.addInputAfter('packageManager', {
+    key: 'test',
+    name: '测试输入',
+    type: 'input'
+})
+```
+
+:::info
+注意事项
+
+1. 添加问题的 key 不能和 Modern.js 提供的项目类型自身的问题的 key 重复
+
+2. 添加问题 `addInputAfter` 的优先级高于 `addInputBefore`，当同时对一个 `key` 添加 After 问题和对其后一个key 添加 Before 问题时，After 问题会在 Before 之前。
+
+3. 当需要在相同 `key` 前面或者后面添加多个问题时，可多次调用该方法，问题的顺序会按照调用顺序进行排列。
+:::

package/zh/apis/generator/plugin/input/addInputBefore.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 2
+---
+
+# addInputBefore
+
+在默认输入前添加输入问题。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export interface IPluginContext {
+  addInputBefore: (key: string, input: IInput) => void;
+  ...
+}
+```
+
+## key
+
+Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/docs/configure/generator/introduce)。
+
+## input
+
+需要添加的问题，具体类型定义可查看[自定义输入相关类型定义](/docs/apis/generator/plugin/input/type)。
+
+## 示例
+
+在包管理工具后面添加输入：
+
+```ts
+context.addInputBefore('packageManager', {
+    key: 'test',
+    name: '测试输入',
+    type: 'input'
+})
+```
+
+:::info
+注意事项
+
+1. 添加问题的 key 不能和 Modern.js 提供的项目类型自身的问题的 key 重复
+
+2. 添加问题 `addInputAfter` 的优先级高于 `addInputBefore`，当同时对一个 `key` 添加 After 问题和对其后一个key 添加 Before 问题时，After 问题会在 Before 之前。
+
+3. 当需要在相同 `key` 前面或者后面添加多个问题时，可多次调用该方法，问题的顺序会按照调用顺序进行排列。
+:::

package/zh/apis/generator/plugin/input/addOptionAfter.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 6
+---
+
+# addOptionAfter
+
+在特定问题的默认选项后 Options 选项。
+
+该方法可直接在 context 上获取。
+
+其类型定义为:
+
+```ts
+export interface IPluginContext {
+  addOptionAfter: (key: string, optionKey: string, option: IOption) => void;
+  ...
+}
+```
+
+## key
+
+问题关键字。
+Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/docs/configure/generator/introduce)。
+
+## optionKey
+
+问题选项关键字。
+Modern.js 工程方案的配置的问题选项关键字，具体配置可查看[生成器配置](/docs/configure/generator/introduce)。
+
+## options
+
+需要添加的选项，具体类型定义可查看[自定义输入相关类型定义](/docs/apis/generator/plugin/input/type)。
+
+## 示例
+
+```ts
+context.addOptionAfter('packageManager', 'pnpm', {
+    key: "npm",
+    name: "NPM"
+});
+```
+
+:::info
+对于 Modern.js 工程类型提供的输入选项，暂时只支持删除，不支持增加，增加会造成代码中的逻辑判断存在问题。上方示例不可直接使用。
+:::

package/zh/apis/generator/plugin/input/addOptionBefore.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 5
+---
+
+# addOptionBefore
+
+在特定问题的默认选项前 Options 选项。
+
+该方法可直接在 context 上获取。
+
+其类型定义为:
+
+```ts
+export interface IPluginContext {
+    addOptionBefore: (key: string, optionKey: string, option: IOption) => void;
+  ...
+}
+```
+
+## key
+
+问题关键字。
+Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/docs/configure/generator/introduce)。
+
+## optionKey
+
+问题选项关键字。
+Modern.js 工程方案的配置的问题选项关键字，具体配置可查看[生成器配置](/docs/configure/generator/introduce)。
+
+## options
+
+需要添加的选项，具体类型定义可查看[自定义输入相关类型定义](/docs/apis/generator/plugin/input/type)。
+
+## 示例
+
+```ts
+context.addOptionBefore('packageManager', 'pnpm', {
+    key: "npm",
+    name: "NPM"
+});
+```
+
+:::info
+对于 Modern.js 工程类型提供的输入选项，暂时只支持删除，不支持增加，增加会造成代码中的逻辑判断存在问题。上方示例不可直接使用。
+:::

package/zh/apis/generator/plugin/input/setInput.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 4
+---
+
+# setInput
+
+设置问题属性。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export interface IPluginContext {
+  setInput: (key: string, field: string, value: unknown) => void;
+  ...
+}
+```
+
+## key
+
+问题关键字，可以为 Modern.js 工程方案的问题关键字，也可以为生成器插件中新增问题的关键字。
+
+## filed
+
+需设置的问题字段，可修改除了当前 Input 除 key 以外的其他字段，Input 具体类型定义可查看[自定义输入相关类型定义](/docs/apis/generator/plugin/input/type)。
+
+## value
+
+需设置的问题字段值。value 支持函数，函数参数为当前字段值，返回值需要为完整的新的字段值。
+
+:::info
+对于 Modern.js 工程类型提供的输入选项，暂时只支持删除，不支持增加，增加会造成代码中的逻辑判断存在问题。
+:::
+
+## 示例
+
+修改 packageName 的展示名称
+
+```ts
+context.setInput('packageName', 'name', "展示名称");
+```

package/zh/apis/generator/plugin/input/setInputValue.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 7
+---
+
+# setInputValue
+
+设置输入默认值。
+
+该方法可直接在 context 上获取。
+
+```ts
+export interface IPluginContext {
+    setInputValue: (value: Record<string, unknown>) => void;
+  ...
+}
+```
+
+## 示例
+
+```ts
+context.setInputValue({
+  moduleRunWay: 'no',
+});
+```
+
+:::warning
+该方法只支持设置生成器插件集成的工程方案对应的配置参数值，不支持设置工程方案类型(solution)和项目场景(scenes)，这两个配置可以通过执行时的 `--config` 参数设置默认值。
+:::

package/zh/apis/generator/plugin/input/type.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 1
+---
+
+# 自定义输入相关类型定义
+
+## Input
+
+输入类型结构，其类型定义为：
+
+```ts
+interface Input {
+    key: string;
+    name: string;
+    type: 'input' | 'radio' | 'checkbox';
+    options?: IOption[];
+    validate?: (value: any, data: Record<string, unknown>, extra?: Record<string, unknown>) => {
+        success: boolean;
+        error?: string;
+    } | Promise<{
+        success: boolean;
+        error?: string;
+    >
+    when?: (input: Record<string, any>, extra?: Record<string, any>) => Promise<boolean>
+}
+```
+
+### key
+
+关键字，作为输入字段的 key，可在生成器插件生命周期中通过 `input[key]` 获取到用户输入。
+
+### name
+
+展示名称。
+
+### type
+
+输入类型，包含三种值:
+
+- input：直接输入类型。
+
+- radio：单选类型，需配合 options 使用。
+
+- checkbox：多选类型，需配合 options 使用。
+
+### options
+
+单选和多选类型时选项，选项结构后续介绍。
+
+### validate
+
+验证函数，当用户输入之后，可在该函数中对输入进行验证。其中：
+
+- value 为当前输入字段值
+
+- data 为当前表单的所有输入字段值
+
+- extra 为从 config 参数额外传入的参数
+
+### when
+
+条件函数，用于控制问题是否展示，当该函数返回 true 时，问题展示。其中:
+
+- input 为当前表单的所有输入字段值
+
+- extra 为从 config 参数额外传入的参数
+
+## Option
+
+option 为输入选项，当自定义 Input 类型为 `radio` 或 `checkbox` 时，需要该配置。
+
+option 类型定义为：
+
+```ts
+interface IOption {
+    key: string;
+    name: string;
+    isDefault?: boolean; // 是否为默认值，存在多个，以第一个选项为主，当前默认选项正好不展示，将会取第一个展示的选项值
+    when?: (input: Record<string, any>, extra?: Record<string, any>) => Promise<boolean> // 问题可根据之前输入决定是否展示
+}
+```
+
+### key
+
+关键字，option 选项的关键字，当选中该选项是，对应 `input` 的值为该字段值。
+
+### name
+
+展示名称。
+
+### isDefault
+
+是否为默认值，设置为 true 时，展示问题会默认选择该选项
+
+### when
+
+条件函数，用于控制选项是否展示，当该函数返回 true 时，问题展示。其中:
+
+- input 为当前表单的所有输入字段值
+
+- extra 为从 config 参数额外传入的参数

package/zh/apis/generator/plugin/introduce.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 1
+---
+
+# 介绍
+
+Modern.js 支持通过生成器插件的方式对提供的工程方案进行定制化或针对工程方案进行特定场景的定制化。
+
+## 生成器插件构成
+
+生成器插件是一个模块，可以直接使用 Modern.js 的模块工程方案开发。当然，Modern.js 也提供了对应的生成器插件(`@modern-js/generator-plugin-plugin`)直接新建生成器插件项目。
+
+一个生成器插件项目目录如下：
+
+```bash
+.
+├── README.md
+├── package.json
+├── src
+│   ├── index.ts
+│   └── modern-app-env.d.ts
+├── templates
+└── tsconfig.json
+```
+
+`src/index.ts` 中为源码目录，用于开发生成器插件逻辑。插件默认导出一个函数，函数参数为 `context`，`context` 上提供一些方法可直接对当前项目进行操作，本章节后续将详细介绍这些方法。
+
+`templates` 目录为模板目录，用于存在生成器插件中需要使用的模板文件。
+
+
+## 生成器插件分类
+
+生成器插件分为两种：
+
+1. 扩展工程方案：直接对默认提供的三大工程方案进行定制化
+
+2. 创建工程方案场景：基于默认的三大工程方案创建对应的工程方案场景
+
+### 类型定义
+
+生成器插件的分类通过 `package.json` 中的 `meta` 信息提供。
+
+#### 扩展工程方案
+
+```json
+{
+    "meta": {
+        "extend": "mwa"
+    }
+}
+```
+
+`extend` 为扩展的工程方案名称，Modern.js 的工程方案名称分别为 `mwa`、`module`、 `monorepo`。
+
+#### 创建工程方案场景
+
+```json
+{
+    "meta": {
+        "key": "new_solution",
+        "name": "新工程方案",
+        "type": "mwa"
+    }
+}
+```
+
+`key` 为场景方案名称，值为字符串。
+`name` 为场景方案展示名称，用与使用时选项的展示，值为字符串。
+`type` 为工程方案类型，除了和 `extend` 一样支持三种工程方案之外，还支持自定义(custom)类型。
+
+### 自定义(custom)类型
+
+自定义类型提供了完全自定义工程方案的实现能力，当使用该类型新建工程方案场景时，只提供了少量的开发层面的最佳实践的代码，比如 `.gitignore`、`.editorConfig` 等文件，具体为下方目录结构：
+
+```
+.
+├── .editorconfig
+├── .gitignore
+├── .idea
+│   ├── codeStyles
+│   │   ├── Project.xml
+│   │   └── codeStyleConfig.xml
+│   ├── inspectionProfiles
+│   │   └── Project_Default.xml
+│   └── jsLinters
+│       └── eslint.xml
+├── .nvmrc
+└── .vscode
+    ├── extensions.json
+    └── settings.json
+```
+
+自定义类型保证了可根据自身对工程方案的需求灵活进行配置。

package/zh/apis/generator/plugin/new/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "启用功能 API",
+  "position": 6
+}

package/zh/apis/generator/plugin/new/createElement.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 2
+---
+
+# createElement
+
+创建工程元素，只支持应用工程方案。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export enum ActionElement {
+  Entry = 'entry',
+  Server = 'server',
+}
+export type ForgedAPI = {
+  createElement: (
+    element: ActionElement,
+    params: Record<string, unknown>,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## element
+
+工程元素类型，支持 entry 和 server。
+
+## params
+
+创建元素的其他参数，详细参考[应用 New 命令](/docs/configure/generator/mwa#new-%E5%91%BD%E4%BB%A4)。