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

package/zh/guides/topic-detail/generator/codesmith/run-in-js.md

@@ -1,48 +0,0 @@
----
-sidebar_position: 4
----
-
-
-# 使用 JS 代码执行微生成器
-
-除了使用 cli 的方式执行微生成器，我们免不了需要在代码中执行微生成器，下面就介绍在 js 代码中如何执行微生成器。
-
-## 安装 codesmith 依赖
-
-```bash
-pnpm add @modern-js/codesmith
-```
-
-## 创建 codesmith 实例
-
-```typescript
-import { CodeSmith, Logger } from '@modern-js/codesmith';
-
-const smith = new CodeSmith({
-   debug: false, // 是否开启 debug 模式，为 true 时会展示生成器中的 debug 信息
-});
-```
-
-## 调用 forge 方法执行生成器
-
-```typescript
-type RunnerTask = Array<{
-  name: string;
-  config: Record<string, any>;
-}>;
-
-const task: RunnerTask = [
-  {
-    name: "generator", // 生成器 npm 包名称
-    config: {}, // 生成器执行的默认配置
-  },
-];
-
-await smith.forge({
-  tasks: task.map(runner => ({
-    generator: runner.name,
-    config: runner.config,
-  })),
-  pwd: '.', // 生成器执行路径
-});
-```

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

@@ -1,86 +0,0 @@
----
-sidebar_position: 2
----
-
-# 微生成器的组成
-
-一个微生成器项目为一个模块项目或者一个 Npm 包，包中包含几个基本部分：
-
-## package.json
-
-npm 包描述信息，包含 name、version、main 等字段。
-
-## 入口文件
-
-上述 main 字段对应的 js 文件。文件为默认导出一个生成器函数，函数格式如下：
-
-```typescript
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-
-};
-```
-
-该函数参数为 context 和 generator：
-
-### context
-
-context 提供 codesmith 运行时维护的上下文信息。其类型定义为：
-
-```typescript
-interface GeneratorContext {
-  materials: Record<string, FsMaterial>; // 资源
-  config: Record<string, any>; // 用户 config 配置
-  data?: Record<string, any>; // 用户 data 配置
-  current: { material: FsMaterial; } | null; //  当前生成器运行可获取的文件资源
-  [key: string]: any; // 其他补充字段
-}
-```
-
-materials 是 codesmith 的抽象文件系统，维护这生成器名称和可操作文件的映射关系。
-
-materials 中还维护这一个 default 的映射关系，用于维护当前生成器执行目录的资源信息，通过该字段可以对目标项目资源进行操作。
-
-例如当需要修改当前项目的 `package.json` 中的字段:
-
-```typescript
-const resource = context.materials.default.get(path.join(appDir, 'package.json'))
-```
-
-将获取到的 resource 传递给 codesmith 提供的 JSON API 即可实现 json 操作。
-
-GeneratorContext 的 current 字段上维护这当前运行的生成器文件资源，可以通过 `current.material` 获取到当前的 `FsMaterial`.
-
-FsMaterial 中提供了 get 方法用于获取资源文件并将资源文件传给生成器支持的 API 即可对模板文件进行处理。
-
-例如：
-
-```typescript
-const resourceMap = await material.find('templates/**/*');
-```
-
-通过上述方式可以获取到生成器中符合 `templates/**/*` 规则的所有模板文件，遍历该对象即可对资源文件进行操作。
-
-### generator
-
-generator 提供 codesmith 运行时的函数方法。其类型定义为：
-
-```typescript
-interface GeneratorCore {
-    logger: Logger; // log 函数，支持 info、warning、debug、error、verbose、stream
-    outputPath: string; // 输出文件路径
-    output: {
-        fs: (file: string | number, data: any, options?: string | fs.WriteFileOptions | undefined) => Promise<void>
-    }; // 写文件方法
-    runSubGenerator: (subGenerator: string, relativePwdPath?: string | undefined, config?: Record<string, any> | undefined): Promise<void> // 运行子生成器
-}
-```
-
-其中 outputPath 和 context 中的 `materials.default` 指向相同的目录，outputPath 用于直接计算目标路径并操作，`materials.default` 用于获取资源文件。
-
-runSubGenerator 提供了在一个微生成器中去运行其他微生成器的方法，该方法将自动更新和维护新的 context 上下文信息。
-
-## Template 文件
-
-生成器模板文件。
-
-推荐在项目根目录创建一个 templates 目录，用于维护该微生成器的模板文件，微生成器执行过程中只能使用自身的模板文件，对于需要共用的模板文件，建议通过共用子生成器实现。

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

@@ -1,106 +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
-
-   - true: 创建到路径 `examples/`
-
-   - false: 创建到路径 `apps/`
-
-* Default: false
-
-作用于 `应用(MWA)` 项目，标识是否为测试项目。
-
-### isPublic
-
-* Type: Boolean
-
-   - true: 创建到路径 `packages/`
-
-   - false: 创建到路径 `features/`
-
-* Default: false
-
-作用于 `模块(Module)` 项目，标识是否需要对外发布。

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/abstract.md

@@ -1,23 +0,0 @@
----
-sidebar_position: 1
----
-
-# 为什么需要生成器插件
-
-Modern.js 提供了应用(MWA)、模块和 Monorepo 三种工程方案，并通过使用 `@modern-js/create` 工具可以创建三种工程方案的初始项目模板，初始项目模板会提供基本的代码开发环境、简单的示例代码及配置等。
-
-Modern.js 提供的初始化模板具有通用性，能满足一些通用的项目开发需求。
-
-当你深度使用 Modern.js 时，必然会发现每次创建的项目都会进行一些针对自身项目的特定的相似改动，比如修改示例代码、增加一些配置、开启某些功能等。
-
-生成器插件可以帮你将这些针对个人或团队特定的改动沉淀下来，在执行 `npx @modern-js/create` 只需简单的带上 `--plugin` 参数即可避免每次创建完项目都需重复性修改项目的工作。
-
-生成器插件是在 Modern.js 提供的初始化模板项目的基础上，提供对模板进行增加、删除、修改的方法，并通过快捷的方式修改 `package.json`、`modernConfig` 配置和开启功能等操作。
-
-生成器插件提供了两种定制化方式：
-
-1. 扩展工程方案：直接对默认提供的三大工程方案进行定制化
-
-2. 创建工程方案场景：基于默认的三大工程方案创建对应的工程方案场景
-
-接下来将会逐步介绍如何使用和开发生成器插件。

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 渲染数据。

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,37 +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
-
-当前用户输入，可用于获取用户当前的输入信息及配置信息。