@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/guides/topic-detail/generator/plugin/api/file/updateModernConfig.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_position: 8
+---
+
+# updateModernConfig
+
+更新 `package.json` 中 `modernConfig` 字段。
+
+该方法可在 `onForged` 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
+  ...
+};
+```
+
+## updateInfo
+
+字段更新信息。
+
+:::info
+该函数为 updateJSONFile 的封装，将自动更新 `package.json` 的 `modernConfig` 字段 `updateInfo` 中只需填写相对于 `modernConfig` 的更新信息即可。
+
+:::

package/zh/guides/topic-detail/generator/plugin/api/hook/afterForged.mdx

@@ -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](/guides/topic-detail/generator/plugin/api/git/isInGitRepo) 和 [NPM API](/guides/topic-detail/generator/plugin/api/npm/install)。
+
+### inputData
+
+当前用户输入，可用于获取用户当前的输入信息及配置信息。

package/zh/guides/topic-detail/generator/plugin/api/hook/onForged.mdx

@@ -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](/guides/topic-detail/generator/plugin/api/file/introduce) 和[启用功能 API](/guides/topic-detail/generator/plugin/api/new/introduce)。
+
+### inputData
+
+当前用户输入，可用于获取用户当前的输入信息及配置信息。

package/zh/guides/topic-detail/generator/plugin/api/info/locale.mdx

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

package/zh/guides/topic-detail/generator/plugin/api/input/addInputAfter.mdx

@@ -0,0 +1,57 @@
+---
+sidebar_position: 3
+---
+
+# addInputAfter
+
+在默认输入后添加输入问题。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export interface IPluginContext {
+  addInputAfter: (key: string, input: Schema) => void;
+  ...
+}
+```
+
+## key
+
+Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/guides/topic-detail/generator/config/common)。
+
+## input
+
+需要添加的问题，具体类型定义可查看[自定义输入相关类型定义](/guides/topic-detail/generator/plugin/api/input/type)。
+
+## 示例
+
+在包管理工具后面添加输入：
+
+```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` 前面或者后面添加多个问题时，可多次调用该方法，问题的顺序会按照调用顺序进行排列。
+
+:::

package/zh/guides/topic-detail/generator/plugin/api/input/addInputBefore.mdx

@@ -0,0 +1,56 @@
+---
+sidebar_position: 2
+---
+
+# addInputBefore
+
+在默认输入前添加输入问题。
+
+该方法可直接在 context 上获取。
+
+其类型定义为：
+
+```ts
+export interface IPluginContext {
+  addInputBefore: (key: string, input: Schema) => void;
+  ...
+}
+```
+
+## key
+
+Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/guides/topic-detail/generator/config/common)。
+
+## input
+
+需要添加的问题，具体类型定义可查看[自定义输入相关类型定义](/guides/topic-detail/generator/plugin/api/input/type)。
+
+## 示例
+
+在包管理工具后面添加输入：
+
+```ts
+context.addInputBefore('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` 前面或者后面添加多个问题时，可多次调用该方法，问题的顺序会按照调用顺序进行排列。
+
+:::

package/zh/guides/topic-detail/generator/plugin/api/input/setInput.mdx

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

package/zh/guides/topic-detail/generator/plugin/api/input/setInputValue.mdx

@@ -0,0 +1,29 @@
+---
+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/guides/topic-detail/generator/plugin/api/input/type.mdx

@@ -0,0 +1,65 @@
+---
+sidebar_position: 1
+---
+
+# 自定义输入相关类型定义
+
+## Input
+
+Modern.js Input 输入类型采用了开源的 [Formily](https://formilyjs.org/) Schema 结果，支持了部分其 Schema 字段。
+
+### type
+
+schema 类型，目前生成器插件输入支持的类型为 `string`、`number` 和 `object` 类型。其中 `object` 用于实现 schema 嵌套，需要和 `properties` 配合使用。
+
+### name
+
+schema 的关键字。
+
+### title
+
+schema 的展示名称。
+
+### default
+
+schema 默认值。
+
+### enum
+
+schema 如果为选择类型，该字段用于定义选项内容。
+
+每个选项支持两个字段：
+
+- value: 选项值。
+
+- label: 展示名称。
+
+### x-validate
+
+schema 的验证规则。这里支持 Formily 的校验方式，具体可参考 [Formily 表单校验](https://formilyjs.org/zh-CN/guide/advanced/validate)。
+
+### x-reactions
+
+schema 字段联动。这里支持 Formily 的联动方式，具体可参考 [Formily 实现联动逻辑](https://formilyjs.org/zh-CN/guide/advanced/linkages)。
+
+### properties
+
+当 schema 类型为 `object` 时，定义其子表单。
+
+## 示例
+
+```ts
+const schema = {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: '开发语言',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+};
+```

package/zh/guides/topic-detail/generator/plugin/api/introduce.mdx

@@ -0,0 +1,92 @@
+---
+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/guides/topic-detail/generator/plugin/api/new/createElement.mdx

@@ -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 命令](/guides/topic-detail/generator/config/mwa#new-命令)。

package/zh/guides/topic-detail/generator/plugin/api/new/createSubProject.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_position: 4
+---
+
+# createSubProject
+
+创建子项目，只支持 Monorepo 工程方案。
+
+该方法可在 `onForged` 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export enum SubSolution {
+  MWA = 'mwa',
+  MWATest = 'mwa_test',
+  Module = 'module',
+  InnerModule = 'inner_module',
+}
+export type ForgedAPI = {
+  createSubProject: (
+    solution: SubSolution,
+    params: Record<string, unknown>,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## solution
+
+子项目工程方案名称。
+
+## params
+
+创建子项目的其他参数，详细参考[Monorepo 创建子项目](/guides/topic-detail/generator/config/monorepo#创建子项目)。

package/zh/guides/topic-detail/generator/plugin/api/new/enableFunc.mdx

@@ -0,0 +1,44 @@
+---
+sidebar_position: 3
+---
+
+# enableFunc
+
+启用功能，支持应用和模块工程方案。
+
+该方法可在 `onForged` 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export enum ActionFunction {
+  UnBundle = 'unbundle',
+  TailwindCSS = 'tailwindcss',
+  BFF = 'bff',
+  MicroFrontend = 'micro_frontend',
+  I18n = 'i18n',
+  Test = 'test',
+  E2ETest = 'e2e_test',
+  Doc = 'doc',
+  Storybook = 'storybook',
+  RuntimeApi = 'runtimeApi',
+  SSG = 'ssg',
+  Polyfill = 'polyfill',
+  Deploy = 'deploy',
+}
+export type ForgedAPI = {
+  enableFunc: (
+    func: ActionFunction,
+    params?: Record<string, unknown> | undefined,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## func
+
+功能名称，根据不用的工程方案支持的功能进行传值。
+
+## params
+
+启用功能时其他参数，详细参考[应用 New 命令](/guides/topic-detail/generator/config/mwa#new-命令)和[模块 New 命令](/guides/topic-detail/generator/config/module#new-命令)。

package/zh/guides/topic-detail/generator/plugin/api/new/introduce.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+---
+
+# 介绍
+
+Modern.js 提供的三个工程方案支持在项目中执行 new 命令创建元素和开启功能。在生成器插件中可直接调用相关 API 默认创建一些元素和开启支持的功能。
+
+不同的工程方案支持的 new 操作
+
+- [应用](/guides/topic-detail/generator/config/mwa#new-命令)
+
+- [模块](/guides/topic-detail/generator/config/module#new-命令)
+
+- [Monorepo](/guides/topic-detail/generator/config/monorepo#创建子项目)