@modern-js/main-doc 2.60.5 → 2.61.0

package/docs/zh/guides/topic-detail/generator/new/option.md

@@ -1,67 +0,0 @@
----
-sidebar_position: 2
----
-
-# CLI 参数
-
-`new` 命令提供了很多配置参数用于配置其执行过程中的行为，可以通过 `--help` 参数进行查看：
-
-```bash
-npm run new --help
-
-Usage: modern new [options]
-
-启用可选功能
-
-Options:
-  --lang <lang>          设置 new 命令执行语言(zh 或者 en)
-  -c, --config <config>  生成器运行默认配置(JSON 字符串)
-  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
-  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
-  --registry <registry>  生成器运行过程中定制 npm Registry
-  -h, --help             display help for command
-```
-
-下面将针对这些参数做详细介绍：
-
-## --lang \<lang>
-
-执行执行语言，支持 `zh` 和 `en`。
-
-默认情况下，`new` 命令会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者不符合使用习惯，可以使用该参数手动指定。
-
-## -c, --config \<config>
-
-指定项目默认配置。
-
-默认情况下，new 命令在执行过程中会出现选择操作类型、开启功能等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
-
-该字段为 JSON 字符串，例如需指定 BFF 框架时：
-
-```bash
-npm run new --config '{"framework": "express"}'
-```
-
-`config` 支持的参数可查看[配置参数](/guides/topic-detail/generator/new/config.html)。
-
-## -d,--debug
-
-展示调试日志。
-
-当在使用过程中遇到问题时，可以使用该参数显示调试日志，方便快速定位问题位置及对问题进行排查。
-
-## --registry \<registry>
-
-指定执行子生成器和获取项目依赖版本的 npm registry。
-
-## --dist-tag \<distTag>
-
-指定生成器版本。
-
-`new` 命令执行过程中会执行更小的微生成器，默认会使用 `latest` 的微生成器版本，使用该参数可以指定执行的微生成器的版本号的版本。
-
-比如使用 `next` 版本：
-
-```bash
-npm run new --dist-tag next
-```

package/docs/zh/guides/topic-detail/generator/new/use.md

@@ -1,74 +0,0 @@
----
-sidebar_position: 1
----
-
-# 使用
-
-在 Web 应用、 Npm 模块中，我们提供了 `new` 命令用于创建项目元素、开启功能和创建子项目。
-
-## Web 应用
-
-Web 应用项目通过 `@modern-js/app-tools` 提供 `new` 命令。
-
-new 命令提供了三种操作类型：
-
-- 创建工程元素
-
-- 启用可选功能
-
-- 自动重构
-
-每种操作类型都提供了对应支持的列表，可根据项目情况进行选择。
-
-例如：
-
-创建新的应用入口：
-
-```bash
-npm run new
-? 请选择你想要的操作 创建工程元素
-? 请选择创建元素类型 新建「应用入口」
-? 请填写入口名称 entry
-```
-
-执行完成后将会在项目 `src` 目录创建新入口对应名称的文件夹及默认入口文件，并且自动帮忙整理之前 `src` 下入口文件到 `package.json` 中 `name` 字段对应的文件夹中。
-
-开启 BFF 功能：
-
-```bash
-npm run new
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「BFF」功能
-? 请选择 BFF 类型 函数模式
-? 请选择运行时框架 Express
-```
-
-执行完成后将会在项目安装 BFF 相关依赖，并创建 api 目录用于 BFF 模块的开发并提供提示信息用于注册 BFF 插件。
-
-:::info
-这里未帮助用户自动注册插件，原因是由于 `modern.config.[tj]s` 在项目生命周期中变化比较复杂，可能存在模块之间互相引用问题，让用户手动注册能保证修改配置的正确性。
-
-在后续定制化的开发中，如果有类似的需求，也可以通过提示的方式给到使用方操作指南，让用户对文件进行手动操作。
-:::
-
-:::warning
-执行 new 命令时可能会出现需要开启的功能不在列表中，需要检查一下项目 `package.json` 中是否已经安装对应功能的插件，如果仍需使用 new 命令开启，需要先手动移除对应的插件依赖。
-:::
-
-## Npm 模块
-
-Npm 模块项目通过 `@modern-js/module-tools` 提供 new 命令。
-
-new 命令提供了启用可选功能的能力。
-
-例如：
-
-开启 Storybook 能力：
-
-```bash
-npm run new
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「Storybook」
-```
-
-执行完成后将会在项目安装 Storybook 插件相关依赖，增加 `storybook` 命令，创建 `stories` 目录用于 Storybook 模块的开发并提供提示信息用于注册 Storybook 插件。

package/docs/zh/guides/topic-detail/generator/plugin/_meta.json

@@ -1,11 +0,0 @@
-[
-  "structure",
-  "category",
-  "use",
-  "context",
-  {
-    "type": "dir",
-    "name": "api",
-    "label": "API"
-  }
-]

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

@@ -1,50 +0,0 @@
----
-sidebar_position: 3
----
-
-# afterForged
-
-`afterForged` 为生成器插件中用于文件操作后其他步骤操作的生命周期函数。
-
-## 类型
-
-```ts
-export type AfterForgedAPI = {
-  isInGitRepo: () => Promise<boolean>;
-  initGitRepo: () => Promise<void>;
-  gitAddAndCommit: (commitMessage: string) => Promise<void>;
-  install: () => Promise<void>;
-};
-
-export type PluginAfterForgedFunc = (api: AfterForgedAPI, inputData: Record<string, unknown>) => Promise<void>;
-
-export interface IPluginContext {
-   afterForged: (func: PluginAfterForgedFunc) => void;
-  ...
-}
-```
-
-## API
-
-下面将分别介绍 api 参数提供的 API。
-
-### isInGitRepo
-
-判断当前项目是否为一个 Git 仓库。
-
-### initGitRepo
-
-初始化当前项目为 Git 仓库。
-
-### gitAddAndCommit
-
-提交当前仓库变更。
-
-参数：
-
-- `commitMessage`: commit 信息。
-
-
-### install
-
-在项目根目录安装依赖。`install` 函数中将根据 `packageManager` 的值使用对应的包管理工具安装依赖。

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

@@ -1,184 +0,0 @@
----
-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

@@ -1,124 +0,0 @@
----
-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 对象。