@modern-js/main-doc 2.1.0 → 2.2.0

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

@@ -0,0 +1,52 @@
+---
+sidebar_position: 4
+---
+
+# addFile
+
+添加单个文件。用于添加 `templates` 目录的单个模板文件或者直接使用模板添加到模板文件。
+
+该方法可用于任何文件类型，对于二进制以外的文件类型，添加文件时会进行 Handlebars 渲染。
+
+该方法可在 `onForged` 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export interface AddFileParams {
+  type: FileType;
+  file: string;
+  template?: string;
+  templateFile?: string;
+  force?: boolean;
+  data?: Record<string, string>;
+}
+export type ForgedAPI = {
+  addFile: (params: AddFileParams) => Promise<void>;
+  ...
+};
+```
+
+## type
+
+文件类型，具体可查看[文件类型](/guides/topic-detail/generator/plugin/api/file/introduce#文件类型)。
+
+## file
+
+创建的目标文件路径。
+
+## template
+
+文件模板，配置该字段值可直接用于模板渲染文件。优先级低于 templateFile。
+
+## templateFile
+
+模板文件，用于渲染的模板文件路径，其值为 `templates` 的相对路径即可。
+
+## force
+
+是否强制覆盖，当添加的文件已存在时，默认会冲突报错，设置该值为 true 时，可强制覆盖。
+
+## data
+
+Handlebars 渲染数据。

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

@@ -0,0 +1,55 @@
+---
+sidebar_position: 5
+---
+
+# addManyFile
+
+批量添加文件。用于添加 `templates` 目录的多个文件。
+
+该方法可用于任何文件类型，对于二进制以外的文件类型，添加文件时会进行 Handlebars 渲染。
+
+该方法可在 `onForged` 生命周期的 `api` 参数上获取。
+
+其类型定义为：
+
+```ts
+export interface AddManyFilesParams {
+  type: FileType;
+  destination: string;
+  templateFiles: string[] | (() => string[]);
+  templateBase?: string;
+  fileNameFunc?: (name: string) => string;
+  data?: Record<string, string>; // template data
+}
+export type ForgedAPI = {
+  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
+  ...
+};
+```
+
+## type
+
+文件类型，具体可查看[文件类型](/guides/topic-detail/generator/plugin/api/file/introduce#文件类型)。
+
+## destination
+
+创建的目标文件夹路径。由于是批量添加文件，这里填写需要写入的文件夹路径即可。
+
+## templateFiles
+
+模板文件列表。
+该参数支持函数参数，也支持 [globby 正则](https://www.npmjs.com/package/globby)。
+
+## templateBase
+
+模板基础路径。
+模板路径通常为同一个目录下的模板文件，如果渲染结果需要去除掉模板文件前缀目录，可使用该字段。
+模板渲染文件内容将等于 `templateFiles - templateBase`
+
+## fileNameFunc
+
+重命名文件函数，在该函数中将一次传入渲染的文件名称，可在该函数中进行重命名。
+
+## data
+
+Handlebars 渲染数据。

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

@@ -0,0 +1,39 @@
+---
+sidebar_position: 1
+---
+
+# 介绍
+
+文件操作 API 可在 `onForged` 生命周期函数中使用，可对当前项目文件进行增、删、改的操作。
+
+文件操作 API 相关路径填写项目相对路径即可，生成器插件会自动添加当前项目路径前缀。
+
+## 文件类型
+
+生成器插件将文件类型分为一下几类：
+
+- 文本文件：纯文本内容文件，可使用 handlebars 进行模板处理的文件。
+
+- 二进制文件：图片、音频、视频等文件
+
+:::warning
+使用变量的 jsx 或 tsx 文件为二进制文件，其语法与 handlebars 渲染冲突，会造成模板文件创建失败。
+
+:::
+
+- JSON 文件：JSON 格式的文件，例如 `package.json`、 `tsconfig.json`。
+
+- 文本列表文件：文件由行文本组成的文件，例如 `.gitignore`, `.editorconfig`, `.npmrc`。
+
+生成器插件的文件操作 API 将是针对这四种文件类型进行操作。
+
+其类型定义为：
+
+```ts
+export enum FileType {
+  Text = 'text',
+  Binary = 'binary',
+  Json = 'json',
+  TextRaw = 'textRaw',
+}
+```

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

@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+---
+
+# updateJSONFile
+
+更新 JSON 文件字段。
+
+该方法适用于 JSON 文件类型，可批量更新 JSON 文件中字段值。
+
+该方法可在 `onForged` 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  updateJSONFile: (
+    fileName: string,
+    updateInfo: Record<string, unknown>,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## fileName
+
+JSON 文件的文件名或者文件路径。
+
+## updateInfo
+
+字段更新信息。
+
+该信息使用 `Record` 形式表示。
+
+例如需要更新 name 字段：
+
+```ts
+api.updateJSONFile(file, {
+  name: '新名称',
+});
+```
+
+需更新嵌套字段：
+
+```ts
+api.updateJSONFile(file, {
+  'dependencies.name': '新名称',
+});
+```
+
+:::warning
+更新嵌套字段时注意字段名，如果不是全量更新，需将嵌套的 key 也写入字段名中。
+
+:::

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/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/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#创建子项目)