@modern-js/main-doc 2.1.0 → 2.3.0

package/zh/guides/topic-detail/framework-plugin/relationship.md

@@ -1,118 +0,0 @@
----
-title: 插件之间的关系
-sidebar_position: 4
----
-
-Modern.js 的插件配置对象提供了一系列的字段，用于控制插件顺序、互斥等能力，可用的字段如下：
-
-- `name`: `string`，设置当前插件的名称。
-- `pre`: `string[]`，这些插件最终会调整到当前插件前面。
-- `post`: `string[]`，这些插件最终会调整到当前插件后面。
-- `rivals`: `string[]`，互斥插件，遇到这些插件时会报错。
-- `required`: `string[]`，必需插件，插件列表中没有对应的插件时会报错。
-- `usePlugin`: `CliPlugin[]`，注册其他插件。
-
-通过以上参数可以实现插件的前置、后置、互斥、必需等逻辑。
-
-## 插件排序
-
-Modern.js 的插件通过 `pre`、`post` 参数来实现了插件排序的功能。
-
-### 前置插件
-
-默认情况下，插件会按照添加顺序依次执行，通过 `pre` 字段可以声明前置执行的插件。
-
-比如有下面两个插件：
-
-```ts title=foo.ts
-const foo = {
-  name: 'plugin-foo',
-};
-```
-
-```ts title=bar.ts
-const bar = {
-  name: 'plugin-bar',
-  pre: ['plugin-foo'],
-};
-```
-
-`bar` 插件在 `pre` 字段中配置了 `foo` 插件，因此 `foo` 插件一定会在 `bar` 插件之前执行。
-
-### 后置插件
-
-同样的，通过 `post` 字段可以声明后置执行的插件。
-
-```ts title=foo.ts
-const foo = {
-  name: 'plugin-foo',
-};
-```
-
-```ts title=bar.ts
-const bar = {
-  name: 'plugin-bar',
-  post: ['plugin-foo'],
-};
-```
-
-`bar` 插件在 `post` 字段中配置了 `foo` 插件，因此 `foo` 插件一定会在 `bar` 插件之后执行。
-
-## 互斥插件
-
-通过 `rivals` 字段可以声明插件间的互斥关系。
-
-有下面两个插件：
-
-```ts title=foo.ts
-const foo = {
-  name: 'plugin-foo',
-};
-```
-
-```ts title=bar.ts
-const bar = {
-  name: 'plugin-bar',
-  rivals: ['plugin-foo'],
-};
-```
-
-`bar` 插件在 `rivals` 字段中配置了 `foo` 插件，因此同时添加了 `foo` 插件和 `bar` 插件就会报错。
-
-## 必需插件
-
-通过 `required` 字段可以声明插件间的依赖关系。
-
-有下面两个插件：
-
-```ts title=foo.ts
-const foo = {
-  name: 'plugin-foo',
-};
-```
-
-```ts title=bar.ts
-const bar = {
-  name: 'plugin-bar',
-  required: ['plugin-foo'],
-};
-```
-
-`bar` 插件在 `required` 字段中配置了 `foo` 插件，因此使用 `bar` 插件时，如果未配置 `foo` 插件就会报错。
-
-## 注册插件
-
-当插件之间存在依赖关系时，我们也可以在一个插件中通过 `usePlugin` 主动注册另一个插件：
-
-```ts title=foo.ts
-const foo = () => ({
-  name: 'plugin-foo',
-});
-
-const bar = () => ({
-  name: 'plugin-bar',
-  usePlugin: [foo()],
-});
-```
-
-当使用者配置了 `bar` 插件时，`foo` 插件也会自动注册生效，使用者就不需要去额外注册 `foo` 插件了。

package/zh/guides/topic-detail/generator/codesmith/api/app.md

@@ -1,152 +0,0 @@
----
-sidebar_position: 1
----
-
-# @modern-js/codesmith-api-app
-
-微生成器开发过程中常用 API 的组合封装，包含 fs、git、npm 等其他包的 API 封装，在能满足需求时，推荐使用该 npm 包的 API。
-
-## 使用姿势
-
-```ts
-import { AppAPI } from '@modern-js/codesmith-api-app';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const appApi = new AppAPI(context, generator);
-  await appApi.runInstall();
-};
-```
-
-- 创建 AppAPI 实例，参数和微生成器函数参数一致，为 context 和 generator，具体介绍请看[微生成器项目组成](/docs/guides/topic-detail/generator/codesmith/structure)。
-- 调用其实例上 API 即可。
-
-## API
-
-### checkEnvironment
-
-检查当前生成器运行环境，检查项为：
-
-1. node 及 node 版本，默认大于 12.22.12，可传递参数执行 node 版本。
-2. 可使用 yarn、pnpm 或者 npm。
-
-参数：
-
-- nodeVersion?: `string` 校验的 node 版本。
-
-### runInstall
-
-安装依赖，可传入安装依赖命令，默认根据 config 中的 `packageManager` 值进行。
-
-参数：
-
-- command?: `string` 安装依赖命令。
-
-### runGitAndInstall
-
-该函数完成以下动作：
-
-1. 校验当前生成器执行目录是否为一个 git 仓库。
-2. 如果不是一个 git 仓库，初始化为一个 git 仓库。
-3. 安装依赖。
-4. 在非 monorepo 项目(判断条件，config 中 `isMonorepoSubProject` 不存在或者为 false)中提交初始 commit，commit 信息为 feat: init，支持自定义。
-
-参数：
-
-- commitMessage?: `string` 初始化 commit message 信息。
-- installFunc?: `() => Promise<void>` 安装依赖函数。
-
-### forgeTemplate
-
-渲染生成器模板文件。
-
-参数：
-
-- templatePattern: string 模板文件匹配正则，例如： `templates/base-templates/**/*` 。
-- filter?: `(resourceKey: string) => boolean` 过滤函数，参数为 templatePattern 匹配的文件路径，返回 true 表示渲染该文件，返回 false 表示不渲染该文件。
-- rename?: `(resourceKey: string) => string` 重命名函数，参数为 templatePattern 匹配的文件路径，返回新文件名。默认会替换 resourceKey 开头的 templates 目录和结尾的 .handlebars 后缀。
-- parameters?: `Record<string, any>` 渲染参数，当模板中存在 handlebars 或者 ejs 变量时，使用其传递对应变量值。
-- type?: `'handlebars' | 'ejs'` 模板文件类型，默认为 handlebars。
-
-例如:
-
-```ts
-await appApi.forgeTemplate(
-  'templates/base-templates/**/*',
-  undefined,
-  resourceKey =>
-    resourceKey
-      .replace('templates/base-templates/', '')
-      .replace('.handlebars', ''),
-);
-
-await appApi.forgeTemplate(
-  'templates/base-template/**/*',
-  resourceKey => !resourceKey.include('eslintrc.json'),
-  resourceKey =>
-    resourceKey
-      .replace('templates/base-template/', projectPath)
-      .replace('language', language as string)
-      .replace('.handlebars', ''),
-  {
-    name: packageName as string,
-    language,
-    isTs: language === Language.TS,
-    packageManager: getPackageManagerText(packageManager as any),
-  },
-);
-```
-
-### showSuccessInfo
-
-展示成功信息。
-
-参数：
-
-- successInfo?: `string`，默认为 Success || 成功。
-
-### runSubGenerator
-
-运行子生成器。
-
-参数：
-
-- subGenerator: `string` 子生成器名称或者路径。
-- relativePwdPath?: `string` 子生成器运行的相对路径。
-- config?: `Record<string, unknown>` 子生成器运行的默认 config 配置。
-
-例如：
-
-```ts
-await appApi.runSubGenerator(
-  getGeneratorPath('@modern-js/repo-generator', context.config.distTag),
-  undefined,
-  { ...context.config, hasPlugin: false },
-);
-```
-
-### getInputBySchema
-
-通过 schema 完成用户交互输入。
-
-参数：
-
-- schema: `FormilySchema | Question[]` 问题列表，支持 Formily schema 和 inquirer 类型。
-- type: `'formily' | 'inquirer'` 类型，默认值为 formily。
-- configValue: `Record<string, unknown> = {}` schema 默认值，传入该值的 schema 字段对应的问题将不再和用户交互。
-- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>` schema 中特殊字段的验证函数。
-- initValue?: `Record<string, any>` schema 中字段的初始化值。
-
-Formily Schema 类型支持方式可参考[自定义输入相关类型定义](/docs/guides/topic-detail/generator/plugin/api/input/type)。
-
-### getInputBySchemaFunc
-
-通过 schema 完成用户交互输入，schema 参数值为函数，用户处理国际化问题，仅支持 Formily schema。
-
-参数：
-
-- schema: `config?: Record<string, any>) => FormilySchema` 获取问题列表函数，config 参数为当前生成器中的 config 配置信息。
-- configValue: `Record<string, unknown> = {}` schema 默认值，传入该值的 schema 字段对应的问题将不再和用户交互。
-- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>` schema 中特殊字段的验证函数。
-- initValue?: `Record<string, any>` schema 中字段的初始化值。
-
-Formily Schema 类型支持方式可参考[自定义输入相关类型定义](/docs/guides/topic-detail/generator/plugin/api/input/type)。

package/zh/guides/topic-detail/generator/codesmith/api/json.md

@@ -1,56 +0,0 @@
----
-sidebar_position: 2
----
-
-# @modern-js/codesmith-api-json
-
-微生成器中 JSON API 封装，提供常见的 JSON 文件操作方法。
-
-## 使用姿势
-
-```ts
-import { JsonAPI } from '@modern-js/codesmith-api-json';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const jsonAPI = new JsonAPI(generator);
-  await jsonAPI.update(context.materials.default.get('package.json'), {
-    query: {},
-    update: {
-      $set: {
-        'dependencies.@modern-js/plugin-bff': `^2.0.0`,
-      },
-    },
-  });
-};
-```
-
-- 创建 JsonAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看[微生成器项目组成](/docs/guides/topic-detail/generator/codesmith/structure)。
-- 调用其实例上 API 即可。
-
-## API
-
-### get
-
-获取 JSON 文件内容。
-
-参数：
-
-- resource: `FsResource`，文件资源，通过 `context.materials.default.get(<filename>)` 获取。
-
-### extend
-
-合并对象至 JSON 文件。
-
-参数：
-
-- resource: `FsResource` 通过 `context.materials.default.get(<filename>)` 获取。
-- obj: `Record<string, any>` 需合并对象。
-
-### update
-
-更新对象字段至 JSON 文件。
-
-参数：
-
-- resource: `FsResource` 通过 `context.materials.default.get(<filename>)` 获取。
-- operation: `{ query: Record<string, any>; update: Record<string, any> }` 更新操作，详细使用姿势查看 [declaration-update](https://www.npmjs.com/package/declaration-update)。

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

@@ -1,52 +0,0 @@
----
-sidebar_position: 3
----
-
-# 开发微生成器项目
-
-## 创建项目
-
-Modern.js 提供了创建微生成器项目的微生成器，可以直接通过以下命令创建微生成器项目：
-
-```bash
-$ mkdir <projectDir>
-$ npx @modern-js/codesmith-cli @modern-js/generator-generator
-
-? 请填写项目名称 <generatorName>
-? 请选择包管理工具 pnpm
-? 请选择开发语言 TS
-```
-
-## 添加模板文件
-
-在项目目录的 templates 文件夹，用于存放生成器需要的模板文件，如果没有模板文件，该步骤可跳过。
-
-## 开发生成器核心逻辑
-
-默认生成的的项目中，已经实现直接拷贝 templates 目录文件至目标项目，可直接在 `handleTemplateFile` 函数中完成生成器的核心逻辑开发。
-
-## 测试微生成器
-
-微生成器开发完成后，需要执行 `pnpm run build` 对代码进行编译，在开发模式下可以使用 `pnpm run build --watch`
-
-codesmith 提供了 cli 工具用于运行和测试微生成器，在目标目录执行使用如下命令执行即可：
-
-```bash
-npx @modern-js/codesmith-cli <generatorPath>
-```
-
-其中 generatorPath 为上述生成器项目的绝对路径。
-
-## 运行微生成器
-
-生成器发布 npm 包之后，使用如下命令执行：
-
-```bash
-npx @modern-js/codesmith-cli <generatorName>
-```
-
-其中 generatorName 为生成器包名。
-
-:::info
-`@modern-js/create` 也支持运行微生成器，可以使用 `npx @modern-js/create --generator <generatorName>` 运行自定义的微生成器。
-:::

package/zh/guides/topic-detail/generator/config/common.md

@@ -1,97 +0,0 @@
----
-sidebar_position: 1
----
-
-# 通用配置
-
-### solution
-
-工程方案类型(solution)，选项如下：
-
-- 应用(mwa)
-
-- 模块(module)
-
-- Monorepo
-
-:::info
-solution 配置只能在 `@modern-js/create` 的 `--config` 参数中使用，不能在生成器插件中通过设置输入默认值的方式使用。
-:::
-
-### scenes
-
-项目场景(scenes)，当使用创建工程方案场景类型的生成器插件时，该值为对应生成器插件的 key 值。
-
-:::info
-scenes 配置只能在 `@modern-js/create` 的 `--config` 参数中使用，不能在生成器插件中通过设置输入默认值的方式使用。
-:::
-
-### language
-
-开发语言(language)，选项如下：
-
-- TS(ts)
-
-- ES6+(js)
-
-### packageManager
-
-包管理工具(packageManager)，选项如下：
-
-- pnpm(pnpm)
-
-- Yarn(yarn)
-
-:::info
-在生成器插件创建工程方案场景的自定义类型(custom)中，默认只提供了 `packageManager` 配置。
-:::
-
-## 其他配置
-
-### noNeedInstall
-
-- Type: `boolean`
-- Default: `false`
-
-是否跳过依赖安装。
-
-### noNeedGit
-
-- Type: `boolean`
-- Default: `false`
-
-是否跳过 git 初始化和提交初始 commit。
-
-### successInfo
-
-- Type: `string`
-- Default: 不同工程方案的命令操作提示
-
-自定义创建项目成功的提示信息。
-
-### isMonorepoSubProject
-
-- Type: `boolean`
-- Default: `false`
-
-是否为 Monorepo 子项目。
-
-### isTest
-
-- Type: `boolean`
-- Default: `false`
-
-作用于应用项目，标识是否为测试项目。
-
-- `true`: 创建到路径 `examples/`
-- `false`: 创建到路径 `apps/`
-
-### isPublic
-
-- Type: `boolean`
-- Default: `false`
-
-作用于模块 (Module) 项目，标识是否需要对外发布。
-
-- `true`: 创建到路径 `packages/`
-- `false`: 创建到路径 `features/`

package/zh/guides/topic-detail/generator/config/module.md

@@ -1,41 +0,0 @@
----
-sidebar_position: 3
----
-
-# 模块
-
-## 项目创建
-
-创建项目时配置，`@modern-js/create` 使用 `--config` 参数时使用的配置，也是在生成器插件中修改和添加 input 时使用的配置。
-
-模块项目默认包含通用配置，通用配置可查看[通用配置](/docs/guides/topic-detail/generator/config/common)。
-
-### packageName
-
-包名(packageName)，字符串类型，为输入值。
-
-## New 命令
-
-模块项目中 new 命令配置， 可以在执行 new 命令时通过 `--config` 参数配置，也可在生成器插件中创建元素和启用功能时使用。
-
-### actionType
-
-New 命令的操作类型(actionType)，类型支持一种：
-
-- function 启用功能
-
-:::info
-在生成器插件中使用启用功能和创建元素时不需要该参数，生成器插件中自动添加该参数。
-:::
-
-### function
-
-可选功能名称(function)，支持如下选项:
-
-- Tailwind CSS(tailwindcss)
-
-- Storybook(storybook)
-
-- Runtime API(runtimeApi)
-
-- 测试(test)

package/zh/guides/topic-detail/generator/config/monorepo.md

@@ -1,28 +0,0 @@
----
-sidebar_position: 4
----
-
-# Monorepo
-
-Monorepo 项目默认只需要 [PackageManager 配置](/docs/guides/topic-detail/generator/config/common#packagemanager)。
-
-## 创建子项目
-
-Monorepo 项目支持通过使用 new 命令创建子项目，子项目类型支持应用、测试应用、模块、内部模块，除了应用和模块各自的配置外，这里还需要一些通用的子项目配置。
-
-### solution
-
-子项目类型(solution)，不同子项目类型字段为:
-
-- 应用(mwa)
-- 应用（测试）(mwa_test)
-- 模块(module)
-- 模块（内部）(inner_module)
-
-### packageName
-
-子项目名称(packageName)，字符串类型。
-
-### packagePath
-
-子项目路径(packagePath)，字符串类型。

package/zh/guides/topic-detail/generator/config/mwa.md

@@ -1,81 +0,0 @@
----
-sidebar_position: 2
----
-
-# 应用
-
-## 项目创建
-
-创建项目时配置，`@modern-js/create` 使用 `--config` 参数时使用的配置，也是在生成器插件中修改和添加 input 时使用的配置。
-
-应用项目创建参数都为[通用配置](/docs/guides/topic-detail/generator/config/common)。
-
-## New 命令
-
-应用项目中 new 命令配置， 可以在执行 new 命令时通过 `--config` 参数配置，也可在生成器插件中创建元素和启用功能时使用。
-
-### actionType
-
-New 命令的操作类型(actionType)，类型支持两种：
-
-- element 创建工程元素
-
-- function 启用功能
-
-:::info
-在生成器插件中使用启用功能和创建元素时不需要该参数，生成器插件中自动添加该参数。
-:::
-
-### element
-
-元素名称(element)，支持两个选项：
-
-- 创建应用入口(entry)
-
-- 新建自定义 Web Serve 源码目录(server)
-
-入口还需要配置具体的配合使用，介绍如下：
-
-#### name
-
-入口名称(name), 字符串类型。
-
-### function
-
-可选功能名称(function)，支持如下选项:
-
-- Tailwind CSS(tailwindcss)
-
-- BFF(bff)
-
-- SSG(ssg)
-
-- 微前端(micro_frontend)
-
-- 单元测试(test)
-
-- Storybook(mwa_storybook)
-
-- 启用「基于 UA 的 Polyfill」功能(polyfill)
-
-- 启用「全局代理」(proxy)
-
-`bff` 和还需要配置具体的配合使用，介绍如下：
-
-#### BFF 相关参数
-
-##### bffType
-
-BFF 类型(bffType)，支持两个选项：
-
-- 函数模式(function)
-
-- 框架模式(framework)
-
-##### framework
-
-BFF 运行时框架(framework)，支持两个选项：
-
-- Express(express)
-
-- Koa(koa)

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

@@ -1,52 +0,0 @@
----
-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
-
-文件类型，具体可查看[文件类型](/docs/guides/topic-detail/generator/plugin/api/file/introduce#文件类型)。
-
-## file
-
-创建的目标文件路径。
-
-## template
-
-文件模板，配置该字段值可直接用于模板渲染文件。优先级低于 templateFile。
-
-## templateFile
-
-模板文件，用于渲染的模板文件路径，其值为 `templates` 的相对路径即可。
-
-## force
-
-是否强制覆盖，当添加的文件已存在时，默认会冲突报错，设置该值为 true 时，可强制覆盖。
-
-## data
-
-Handlebars 渲染数据。