@modern-js/main-doc 2.1.0 → 2.3.0

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

@@ -1,55 +0,0 @@
----
-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
-
-文件类型，具体可查看[文件类型](/docs/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.md

@@ -1,38 +0,0 @@
----
-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.md

@@ -1,53 +0,0 @@
----
-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.md

@@ -1,26 +0,0 @@
----
-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.md

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

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

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

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

@@ -1,56 +0,0 @@
----
-sidebar_position: 3
----
-
-# addInputAfter
-
-在默认输入后添加输入问题。
-
-该方法可直接在 context 上获取。
-
-其类型定义为：
-
-```ts
-export interface IPluginContext {
-  addInputAfter: (key: string, input: Schema) => void;
-  ...
-}
-```
-
-## key
-
-Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/docs/guides/topic-detail/generator/config/common)。
-
-## input
-
-需要添加的问题，具体类型定义可查看[自定义输入相关类型定义](/docs/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.md

@@ -1,55 +0,0 @@
----
-sidebar_position: 2
----
-
-# addInputBefore
-
-在默认输入前添加输入问题。
-
-该方法可直接在 context 上获取。
-
-其类型定义为：
-
-```ts
-export interface IPluginContext {
-  addInputBefore: (key: string, input: Schema) => void;
-  ...
-}
-```
-
-## key
-
-Modern.js 工程方案的配置的问题关键字，具体配置可查看[生成器配置](/docs/guides/topic-detail/generator/config/common)。
-
-## input
-
-需要添加的问题，具体类型定义可查看[自定义输入相关类型定义](/docs/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.md

@@ -1,42 +0,0 @@
----
-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/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.md

@@ -1,28 +0,0 @@
----
-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.md

@@ -1,33 +0,0 @@
----
-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/guides/topic-detail/generator/config/mwa#new-命令)。

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

@@ -1,35 +0,0 @@
----
-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 创建子项目](/docs/guides/topic-detail/generator/config/monorepo#创建子项目)。

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

@@ -1,44 +0,0 @@
----
-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 命令](/docs/guides/topic-detail/generator/config/mwa#new-命令)和[模块 New 命令](/docs/guides/topic-detail/generator/config/module#new-命令)。

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

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

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

@@ -1,124 +0,0 @@
----
-sidebar_position: 3
----
-
-# 如何开发生成器插件
-
-## 创建项目
-
-Modern.js 提供了创建生成器插件项目的生成器插件用于创建项目，可直接执行以下命令创建:
-
-```bash
-npx @modern-js/create plugin --plugin @modern-js/generator-plugin-plugin
-```
-
-插件类型不同，会提问不同的问题，可根据需求选择插件类型
-
-### 扩展类型
-
-```
-? 请选择你想创建的工程类型 模块
-? 请选择项目场景 生成器插件
-? 插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 插件类型 扩展
-? 插件基础类型 应用
-```
-
-### 自定义类型
-
-```
-? 请选择你想创建的工程类型 模块
-? 请选择项目场景 生成器插件
-? 插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 插件类型 自定义
-? 插件关键字 mobile-app
-? 插件展示名称 移动应用
-? 插件基础类型 应用
-```
-
-创建项目命令执行完成后，会对应的生成一个开发生成器插件的项目，`package.json` 中也会根据你的选择对应的生成 `meta` 信息。
-
-:::info
-生成器插件开发可参考 `@modern-js/generator-plugin-plugin` [源码地址](https://github.com/modern-js-dev/modern.js/tree/main/packages/generator/plugins/generator-plugin)
-:::
-
-## 开发插件逻辑
-
-在 `src/index.ts` 中完成插件逻辑开发。
-
-插件默认导出一个函数，函数参数为 `context`，`context` 上提供一些方法可直接对当前项目进行操作。
-
-简单介绍一下提供的方法，完整的 API 列表可查看[生成器插件 API](/docs/guides/topic-detail/generator/plugin/api/introduce)。
-
-### 自定义输入
-
-- addInputBefore
-
-在默认的输入前添加输入，比如在`选择包管理工具`问题前添加问题，具体 Modern.js 每个问题的配置可查看[工程方案配置](/docs/guides/topic-detail/generator/config/common)。
-
-```ts
-context.addInputBefore('input2', {
-  type: 'object',
-  properties: {
-    'input1.2': {
-      type: 'string',
-      title: 'input1.2',
-    },
-  },
-});
-```
-
-- setInput
-
-设置已经存在问题的属性
-
-```ts
-context.setInput('test', 'type', 'number');
-context.setInput('test', 'enum', [{ value: 'option1', label: '选项一' }]);
-```
-
-### onForged
-
-工程方案类型文件相关操作执行完成后钩子，多个扩展产检将按照 `plugin` 参数顺序依次执行其 `onForged` 函数。
-
-`onForged` 参数是一个回调函数，函数参数为 `api` 和 `input`。
-
-`api` 上会提供一些文件操作相关的方法，可在该钩子中对当前的模板文件进行操作。
-
-`input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
-
-当需要新的模板文件时，可直接在 `templates` 目录添加，在 `onForged` 函数中可直接对 `templates` 目录文件进行操作，比如下方的 `addFile` 中 `templateFile` 参数就为 `templates` 目录下的文件。这里不需要显示的声明 `templates`，直接写相对于 `templates` 的相对路径即可。
-
-`onForged` 中支持的 API 函数也可参考 [生成器插件 API](/docs/guides/topic-detail/generator/plugin/api/hook/onForged)。
-
-```ts
-context.onForged(async (api: ForgedAPI, input: Record<string, unknown>) => {
-  const { language } = input;
-  api.addFile({
-    type: FileType.Text,
-    file: `src/index.${language as string}`,
-    templateFile: `index.${language as string}.handlebars`,
-    force: true,
-  });
-});
-```
-
-### afterForged
-
-`onForged` 函数执行完成后钩子，这里主要可进行安装依赖，Git 操作等。
-
-如果你的工程方案是基于 Modern.js 提供的三种工程方案进行的，这个钩子函数是可以不需要的。默认的工程方案中会自动包含安装依赖、提交代码逻辑。
-
-生成器插件还支持了一种自定义的 `custom` 类型，这种类型只提供了少量的开发层面的最佳实践的代码，比如 `.gitignore`、`.editorConfig` 等文件，这时则需要在 `afterForged` 函数中手动补充安装依赖和 Git 操作逻辑。
-
-`afterForged` 参数也是一个回调函数，函数参数为 `api` 和 `input`。
-
-`api` 上会提供一些 npm、Git 等方法，可在该钩子中进行安装依赖，Git 操作。
-
-`input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
-
-`afterForged` 中支持的 API 函数也可参考 [生成器插件 API](/docs/guides/topic-detail/generator/plugin/api/hook/afterForged)。