@modern-js/main-doc 2.21.0 → 2.22.0

package/docs/zh/guides/topic-detail/generator/codesmith/api/fs.mdx

@@ -1,54 +0,0 @@
----
-sidebar_position: 3
----
-
-# @modern-js/codesmith-api-fs
-
-微生成器中文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。FsAPI 通常用于处理二进制文件或者不能使用 handlebars、ejs 处理的模板文件。
-
-## 使用姿势
-
-```ts
-import { FsAPI } from '@modern-js/codesmith-api-fs';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const fsApi = new FsAPI(generator);
-  await fsApi.renderFile(
-     material.get('templates/a.js'),
-     target: 'b.js'
-   );
-}
-```
-
-- 创建 FsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
-- 调用其实例上 API 即可。
-
-## API
-
-### renderFile
-
-渲染单个模板文件。
-
-参数：
-
-- resource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
-- target: `string` 目标文件路径名称。
-
-### renderDir
-
-渲染模板文件夹。
-
-参数：
-
-- material: `FsMaterial` 当前微生成器执行的 material 上下文。
-- findGlob: `string` 模板文件匹配正则。
-- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
-- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
-
-```ts
-type RenderTemplateDirOptions = {
-  nodir?: boolean;
-  dot?: boolean;
-  ignore?: string | readonly string[];
-};
-```

package/docs/zh/guides/topic-detail/generator/codesmith/api/git.mdx

@@ -1,49 +0,0 @@
----
-sidebar_position: 4
----
-
-# @modern-js/codesmith-api-git
-
-微生成器中使用 git 相关操作的 API 封装，提供判断 git 仓库，初始化及提交代码等方法。
-
-## 使用姿势
-
-```ts
-import { GitAPI } from '@modern-js/codesmith-api-git';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const gitApi = new GitAPI(generatorCore, generatorContext);
-  await gitApi.initGitRepo();
-};
-```
-
-- 创建 GitAPI 实例，参数和微生成器函数参数一致，为 context 和 generator，具体介绍请看微生成器项目组成
-- 调用其实例上 API 即可。
-
-## API
-
-### isInGitRepo
-
-当前目录是否为 git 仓库。
-
-参数：
-
-- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。
-
-### initGitRepo
-
-初始化为 git 仓库。init 的默认分支名可通过生成器 config 中的 defaultBranch 进行配置。
-
-参数：
-
-- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。
-- force?: `boolean` 当前目录已经为 git 仓库时使用该参数会强制执行 git init。
-
-### addAndCommit
-
-执行 `git add .` 和 `git commit` 提交当前变更。
-
-参数：
-
-- commitMessage: `string` commit 信息。
-- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。

package/docs/zh/guides/topic-detail/generator/codesmith/api/handlebars.mdx

@@ -1,56 +0,0 @@
----
-sidebar_position: 5
----
-
-# @modern-js/codesmith-api-handlebars
-
-微生成器中使用 [handlebars](https://handlebarsjs.com/) 进行文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。
-
-## 使用姿势
-
-```ts
-import { HandlebarsAPI } from '@modern-js/codesmith-api-handlebars';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const handlebarApi = new HandlebarsAPI(generator);
-  await handlebarsAPI.renderTemplate(
-     material.get('templates/a.js'),
-     target: 'b.js',
-     { data: "data" }
-   );
-}
-```
-
-- 创建 HandlebarsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
-- 调用其实例上 API 即可。
-
-## API
-
-### renderTemplate
-
-渲染单个模板文件。
-
-参数：
-
-- templateResource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
-- target: `string` 目标文件路径名称。
-- parameters?: `Record<string, string>` 渲染参数。
-
-### renderTemplateDir
-
-渲染模板文件夹。
-
-参数：
-
-- material: `FsMaterial` 当前微生成器执行的 material 上下文。
-- findGlob: `string` 模板文件匹配正则。
-- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
-- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
-
-```ts
-type RenderTemplateDirOptions = {
-  nodir?: boolean;
-  dot?: boolean;
-  ignore?: string | readonly string[];
-};
-```

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

@@ -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，具体介绍请看[微生成器项目组成](/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/docs/zh/guides/topic-detail/generator/codesmith/api/npm.mdx

@@ -1,47 +0,0 @@
----
-sidebar_position: 7
----
-
-# @modern-js/codesmith-api-npm
-
-微生成器中 NPM API 封装，提供常见的 NPM 不同包管理工具安装依赖的方法。
-
-## 使用姿势
-
-```ts
-import { NpmAPI } from '@modern-js/codesmith-api-npm';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const npmApi = new NpmAPI(generator);
-  await npmApi.pnpmInstall();
-};
-```
-
-- 创建 NpmAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
-- 调用其实例上 API 即可。
-
-## API
-
-### npmInstall
-
-使用 npm 安装依赖。
-
-参数：
-
-- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。
-
-### yarnInstall
-
-使用 yarn 安装依赖。
-
-参数：
-
-- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。
-
-### pnpmInstall
-
-使用 pnpm 安装依赖。
-
-参数：
-
-- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。

package/docs/zh/guides/topic-detail/generator/codesmith/develop.mdx

@@ -1,53 +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@latest --generator <generatorName>` 运行自定义的微生成器。
-
-:::

package/docs/zh/guides/topic-detail/generator/codesmith/introduce.mdx

@@ -1,59 +0,0 @@
----
-sidebar_position: 1
----
-
-# 什么是微生成器
-
-Modern.js 提供了 `@modern-js/create` 工具和 `new` 命令分别用于初始化创建项目和提供开启一些插件功能的能力，这些工具都是基于微生成器也就是 codesmith 实现的。
-
-codesmith 致力于提供一套微生成器的运行机制，并维护微生成器执行过程中的上下文信息，从而实现各种基于文件、命令等操作，完成复杂的操作。
-
-codesmith 还将常用的方法进行了封装，可以直接使用其提供的 API 函数，可以更方便的实现自身的微生成器。
-
-## 核心概念
-
-### GeneratorCore
-
-GeneratorCore 是 codesmith 运行生成器的核心，维护这生成器执行过程中的上下文及运行方法。
-
-```ts
-class GeneratorCore {
-  logger: ILogger; // 日志
-  materialsManager: MaterialsManager; // 资源
-  outputPath: string; // 输出路径
-  output: {
-    // 输出方法
-    fs: (
-      file: string | number,
-      data: any,
-      options?: fs.WriteFileOptions | string,
-    ) => Promise<void>;
-  };
-  _context: GeneratorContext; // 上下文信息
-  addMaterial(key: string, material: FsMaterial): void; // 添加资源
-  runGenerator(
-    generator: string,
-    config?: Record<string, unknown>,
-  ): Promise<void>; // 运行生成器
-  runSubGenerator(
-    subGenerator: string,
-    relativePwdPath?: string,
-    config?: Record<string, any>,
-  ): Promise<void>; // 运行子生成器
-}
-```
-
-### Materials
-
-微生成器资源信息，目前只包含文件资源(fsMaterials)，通过该字段可以获取到生成器执行过程中的 template 资源，并通过 API 对其进行操作。
-
-```ts
-class MaterialsManager {
-  materialMap: {
-    // 资源映射关系
-    [materialUri: string]: FsMaterial;
-  };
-  loadLocalGenerator(generator: string): Promise<FsMaterial>; // 加载本地生成器资源(绝对路径)
-  loadRemoteGenerator(generator: string): Promise<FsMaterial>; // 加载远程生成器资源(npm 包)
-}
-```

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

@@ -1,47 +0,0 @@
----
-sidebar_position: 4
----
-
-# 使用 JS 代码执行微生成器
-
-除了使用 cli 的方式执行微生成器，我们免不了需要在代码中执行微生成器，下面就介绍在 js 代码中如何执行微生成器。
-
-## 安装 codesmith 依赖
-
-```bash
-pnpm add @modern-js/codesmith
-```
-
-## 创建 codesmith 实例
-
-```ts
-import { CodeSmith, Logger } from '@modern-js/codesmith';
-
-const smith = new CodeSmith({
-  debug: false, // 是否开启 debug 模式，为 true 时会展示生成器中的 debug 信息
-});
-```
-
-## 调用 forge 方法执行生成器
-
-```ts
-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/docs/zh/guides/topic-detail/generator/codesmith/structure.mdx

@@ -1,89 +0,0 @@
----
-sidebar_position: 2
----
-
-# 微生成器的组成
-
-一个微生成器项目为一个模块项目或者一个 Npm 包，包中包含几个基本部分：
-
-## package.json
-
-npm 包描述信息，包含 name、version、main 等字段。
-
-## 入口文件
-
-上述 main 字段对应的 js 文件。文件为默认导出一个生成器函数，函数格式如下：
-
-```ts
-export default async (
-  context: GeneratorContext,
-  generator: GeneratorCore,
-) => {};
-```
-
-该函数参数为 context 和 generator：
-
-### context
-
-context 提供 codesmith 运行时维护的上下文信息。其类型定义为：
-
-```ts
-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` 中的字段:
-
-```ts
-const resource = context.materials.default.get(
-  path.join(appDir, 'package.json'),
-);
-```
-
-将获取到的 resource 传递给 codesmith 提供的 JSON API 即可实现 json 操作。
-
-GeneratorContext 的 current 字段上维护这当前运行的生成器文件资源，可以通过 `current.material` 获取到当前的 `FsMaterial`.
-
-FsMaterial 中提供了 get 方法用于获取资源文件并将资源文件传给生成器支持的 API 即可对模板文件进行处理。
-
-例如：
-
-```ts
-const resourceMap = await material.find('templates/**/*');
-```
-
-通过上述方式可以获取到生成器中符合 `templates/**/*` 规则的所有模板文件，遍历该对象即可对资源文件进行操作。
-
-### generator
-
-generator 提供 codesmith 运行时的函数方法。其类型定义为：
-
-```ts
-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/docs/zh/guides/topic-detail/generator/config/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "工程方案配置",
-  "position": 3
-}

package/docs/zh/guides/topic-detail/generator/config/app.mdx

@@ -1,82 +0,0 @@
----
-sidebar_position: 2
----
-
-# Web 应用
-
-## 项目创建
-
-创建项目时配置，`@modern-js/create` 使用 `--config` 参数时使用的配置，也是在生成器插件中修改和添加 input 时使用的配置。
-
-应用项目创建参数都为[通用配置](/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/docs/zh/guides/topic-detail/generator/config/common.mdx

@@ -1,100 +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
-
-- **类型：** `boolean`
-- **默认值：** `false`
-
-是否跳过依赖安装。
-
-### noNeedGit
-
-- **类型：** `boolean`
-- **默认值：** `false`
-
-是否跳过 git 初始化和提交初始 commit。
-
-### successInfo
-
-- **类型：** `string`
-- **默认值：** 不同工程方案的命令操作提示
-
-自定义创建项目成功的提示信息。
-
-### isMonorepoSubProject
-
-- **类型：** `boolean`
-- **默认值：** `false`
-
-是否为 Monorepo 子项目。
-
-### isTest
-
-- **类型：** `boolean`
-- **默认值：** `false`
-
-作用于应用项目，标识是否为测试项目。
-
-- `true`: 创建到路径 `examples/`
-- `false`: 创建到路径 `apps/`
-
-### isPublic
-
-- **类型：** `boolean`
-- **默认值：** `false`
-
-作用于模块 (Module) 项目，标识是否需要对外发布。
-
-- `true`: 创建到路径 `packages/`
-- `false`: 创建到路径 `features/`