@modern-js/main-doc 2.60.5 → 2.61.0

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

@@ -1,310 +0,0 @@
----
-sidebar_position: 2
----
-
-# onForged
-
-`onForged` 为生成器插件中用于文件操作的生命周期函数。
-
-## 类型
-
-```ts
-export type ForgedAPI = {
-  addFile: (params: AddFileParams) => Promise<void>;
-  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
-  updateJSONFile: (fileName: string, updateInfo: Record<string, unknown>) => Promise<void>;
-  updateTextRawFile: (fileName: string, update: (content: string[]) => string[]) => Promise<void>;
-  updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
-  rmFile: (fileName: string) => Promise<void>;
-  rmDir: (dirName: string) => Promise<void>;
-  addHelper: (name: string, fn: Handlebars.HelperDelegate) => void;
-  addPartial: (name: string, str: Handlebars.Template) => void;
-  createElement: (element: ActionElement, params: Record<string, unknown>) => Promise<void>;
-  enableFunc: (func: ActionFunction, params?: Record<string, unknown> | undefined) => Promise<void>;
-};
-
-export type PluginForgedFunc = (
-  api: ForgedAPI,
-  inputData: Record<string, unknown>,
-) => void | Promise<void>;
-
-export interface IPluginContext {
-  onForged: (func: PluginForgedFunc) => void;
-  ...
-}
-```
-
-`onForged` 参数为一个回调函数，回调函数参数为 `api` 和 `input`，分别用于提供该生命周期函数提供的 API 及当前输入信息。
-
-## 概念
-
-### 文件类型
-
-生成器插件将文件类型分为四类：
-
-- 文本文件
-
-纯文本内容文件，可使用 [Handlebars](https://handlebarsjs.com/) 或 [EJS](https://ejs.co/) 进行模板处理的文件。
-
-- 二进制文件
-
-图片、音频、视频等文件。
-
-- JSON 文件
-
-JSON 格式的文件。
-
-- 文本列表文件
-
-文件由行文本组成的文件，例如 `.gitignore`, `.editorconfig`, `.npmrc`。
-
-对应四种文件的类型定义为：
-
-```ts
-export enum FileType {
-  Text = 'text',
-  Binary = 'binary',
-  Json = 'json',
-  TextRaw = 'textRaw',
-}
-```
-
-## API
-
-下面将分别介绍 api 参数提供的 API。
-
-### addFile
-
-添加单个文件。
-
-参数类型：
-
-```ts
-export interface AddFileParams {
-  type: FileType;
-  file: string;
-  template?: string;
-  templateFile?: string;
-  force?: boolean;
-  data?: Record<string, string>;
-}
-```
-
-- `type`： 文件类型。
-- `file`：目标文件路径，相对于目标项目目录的相对路径。
-- `template`：模板内容，该字段值可直接用于模板渲染文件。优先级低于 `templateFile`。
-- `templateFile`：模板文件路径，相对于 templates 目录的相对路径即可。
-- `force`：是否强制覆盖，当目标文件存在时是否强制覆盖，默认为 false。
-- `data`：模板渲染数据。
-
-:::info
-文本类型文件默认使用 Handlebars 进行处理，当模板文件以 `.ejs` 结尾的话，会使用 [EJS](https://ejs.co/) 进行模板渲染。
-:::
-
-例如添加模板文件 `App.tsx.hanlebars` 到 `src/App.tsx` 中:
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.addFile({
-    type: FileType.Text,
-    file: `src/App.tsx`,
-    templateFile: `App.tsx.handlebars`,
-  });
-})
-```
-
-### addManyFiless
-
-批量添加文件，一般用于添加多个文件到同一个目标目录。
-
-参数类型：
-
-```ts
-export interface AddManyFilesParams {
-  type: FileType;
-  destination: string;
-  templateFiles: string[] | (() => string[]);
-  templateBase?: string;
-  fileNameFunc?: (name: string) => string;
-  data?: Record<string, string>;
-}
-```
-
-- `type`： 文件类型。
-- `destination`：目标文件夹，相对于目标项目目录的相对路径。
-- `templateFiles`：模板文件列表，支持 [globby](https://www.npmjs.com/package/globby) 正则表达式
-- `templateBase`：模板文件的公共路径，使用该参数时目标文件会自动删除该路径。
-- `fileNameFunc`：重命名文件函数，添加文件过程中会依次将文件名传入到该函数，可以根据需要进行重命名。
-- `data`：模板渲染数据。
-
-例如将模板文件 `src-ts` 目录下所有文件渲染到 `src` 目录：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.addManyFiles({
-    type: FileType.Text,
-    destination: 'src',
-    templateFiles: ['src-ts/**/*'],
-    templateBase: 'src-ts',
-    fileNameFunc: name => name.replace('.handlebars', ''),
-  });
-})
-```
-
-### updateJSONFile
-
-更新 JSON 文件字段。
-
-参数类型：
-
-```ts
-fileName: strings
-updateInfo: Record<string, unknown>
-```
-
-- `fileName`：JSON 文件路径，相对于目标项目的路径。
-- `updateInfo`：更新信息，嵌套字段更新需要平铺，不然会更新整体造成内容丢失。
-
-例如更新 `package.json` 的 name 字段：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateJSONFile('package.json', { name: 'new_name' });
-})
-```
-
-例如更新 `dependencies` 的 `react-dom` 版本:
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateJSONFile('package.json', {
-    'dependencies.react-dom': '^18',
-  });
-})
-```
-
-### updateTextRawFile
-
-更新文本列表文件内容。
-
-参数类型：
-
-```ts
-fileName: string
-update: (content: string[]) => string[]
-```
-
-- `fileName`： 文本列表文件路径，相对于目标项目的路径。
-- `update`：更新函数，参数为当前文件内容以 `\n` 进行分割的数组，返回值也为修改完成后的数组，`@modern-js/create` 会自动以 `\n` 合并，并写入源文件。
-
-例如 `.gitinore` 文件中增加 dist 目录：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateTextRawFile('.gitinore', (content) => [...content, 'dist']);
-})
-```
-
-### updateModernConfig(不推荐)
-
-Modern.js 配置除了可以在 `modern.config.[tj]s` 中配置外，还支持 `package.json` 中配置 `modernConfig` 配置。该函数用于更新该字段。
-
-参数类型：
-
-```ts
-updateInfo: Record<string, any>
-```
-
-- `updateInfo`： 更新内容信息。updateModernConfig 是基于 updateJSONFile 的封装，将自动更新到 `modernConfig` 字段下，updateInfo 中只需填写 `modernConfig` 下的配置字段即可。
-
-例如开启 ssr：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateModernConfig({ 'server.ssr': true });
-})
-```
-
-### rmFile
-
-删除文件。
-
-参数类型：
-
-```ts
-fileName: string
-```
-
-- `fileName`：删除的文件路径，相对于目标项目的路径。
-
-### rmDir
-
-删除文件夹。
-
-参数类型：
-
-```ts
-dirName: string
-```
-
-- `dirName`：删除的文件夹路径，相对于目标项目的路径。
-
-### addHelper
-
-添加 handlebrs 渲染的[自定义 Helper](https://handlebarsjs.com/guide/#custom-helpers)。
-
-参数类型：
-
-```ts
-name: string
-fn: Handlebars.HelperDelegate
-```
-
-- `name`：Helper 函数名称。
-- `fn`：Helper 函数实现。
-
-### addPartial
-
-添加 Handlebars 渲染的 [Partial](https://handlebarsjs.com/guide/partials.html#basic-partials)。
-
-参数类型：
-
-```ts
-name: string
-str: Handlebars.Template
-```
-
-- `name`：Partial 名称。
-- `str`：Partial 的模板字符串。
-
-### createElement
-
-自动调用 new 命令创建工程元素。
-
-参数类型：
-
-```ts
-element: ActionElement
-params: Record<string, unknown>
-```
-
-- `element`：工程元素类型，新建入口或者新建自定义 Web Server 源码目录。
-- `params`：对应创建工程元素的其他参数。
-
-### enableFunc
-
-自动调用 new 命令开启可选功能。
-
-参数类型：
-
-```ts
-func: ActionFunction
-params?: Record<string, unknown>
-```
-
-- `func`：开启功能名称。
-- `params`：对应开启功能的其他参数。
-
-:::info
-创建工程元素和开启功能配置可参考[配置参数](/guides/topic-detail/generator/new/config.html)。
-:::

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

@@ -1,93 +0,0 @@
----
-sidebar_position: 2
----
-
-# 类型
-
-## 介绍
-
-生成器插件分为两类：
-
-- 扩展：Web 应用( Npm 模块) = Web 应用( Npm 模块) + 生成器插件
-
-- 自定义：新应用(模块) = Web 应用(模块) + 生成器插件
-
-
-简单理解就是扩展还是使用 Modern.js 原本的工程方案名称，自定义会创建一个新的名称。
-
-## 标识
-
-生成器插件的类型通过 `package.json` 中的 meta 字段来提供：
-
-### 扩展
-
-```json title="package.json"
-{
- "meta": {
-    "extend": "mwa" // module
- }
-}
-```
-
-### 自定义
-
-```json title="package.json"
-{
- "meta": {
-    "key": "new_app",
-    "name": "新应用",
-    "type": "mwa" // module 和 custom
- }
-}
-```
-
-:::info
-自定义类型的 type 支持 custom 类型，custom 为使用 Modern.js 提供的一些项目开发的最佳实践模板，比如 `.gitignore`、`.editorConfig` 等文件，其他业务相关代码模板需要手动通过生成器插件提供。
-:::
-
-## 创建初始项目
-
-### 扩展
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? 请选择你想创建的工程类型 Npm 模块
-? 请选择项目场景 生成器插件
-? 请输入生成器插件插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请选择插件类型 extend
-? 请选择插件基础类型 Web 应用
-```
-
-### 自定义
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? 请选择项目类型 生成器插件
-? 请选择项目组织方式 独立项目
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请输入生成器插件插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请选择插件类型 custom
-? 请输入插件关键字 new_app
-? 请输入插件展示名称 新应用
-? 请选择插件基础类型 Web 应用
-```
-
-## 执行顺序
-
-生成器插件支持同时使用多个，也就是执行 `@modern-js/create` 时支持多个 `--plugin` 参数。
-
-### 扩展
-
-扩展生成器插件支持在执行时会按照声明的生成器插件参数的顺序，依次执行对应 extend 的工程方案的生命周期函数。
-
-例如存在 A 和 B 两个生成器插件，A 和 B 都是 extend 的 Web 应用工程方案，A 插件声明添加 `a.ts` 文件，B 插件声明添加 `b.ts` 文件，
-执行 `npx @modern-js/create@latest --plugin A --plugin B` 时，选择 Web 应用工程时，会先生成 Web 应用默认的项目文件，然后执行 A 插件创建 `a.ts` 文件，再执行 B 插件，生成 `b.ts` 文件。
-
-### 自定义
-
-自定义生成器插件只支持同一时间运行一个生成器插件，当 `@modern-js/create` 声明 `--plugin` 参数时，会在选择工程方案之后增加选择工程方案场景选项，即为上述 `package.json` 中定义的新 name，选择对应 name 的生成器插件，即会在默认工程方案执行完成后，执行对应的生成器插件逻辑。声明 `--plugin` 参数时，工程方案场景下将会逐一列举出对应的生成器插件名称供选择。

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

@@ -1,105 +0,0 @@
----
-sidebar_position: 4
----
-
-# Context
-
-生成器插件默认会导出一个函数，函数参数为 `context`，在执行过程中 `context` 会自动注入到生成器插件中。
-
-```ts title="src/index.ts"
-import { IPluginContext, ForgedAPI } from '@modern-js/generator-plugin';
-
-export default function (context: IPluginContext) {
-  context.onForged(async (_api: ForgedAPI, _input: Record<string, unknown>) => {
-    /**
-     * Todo
-     */
-  });
-}
-```
-
-`context` 提供了两类 API，分别用于自定义 Input 和定义生成器插件声明周期逻辑。
-
-:::info
-下面只对部分 API 做简单示例讲解，完整的 API 请移步 [生成器插件 API](/guides/topic-detail/generator/plugin/api/context.html) 查看。
-:::
-
-## 自定义 Input
-
-Modern.js Framework 和 Modern.js Module 都存在一些默认的 Input 交互，使用这里的 API 可以对这些 Input 进行添加、修改、隐藏、提供默认值等操作。
-
-例如：
-
-- 添加问题
-
-```ts
-context.addInputBefore('packageManager', {
-  type: 'object',
-  properties: {
-    'username': {
-      type: 'string',
-      title: '用户名',
-    },
-  },
-});
-```
-
-- 通过设置 config 隐藏问题
-
-```ts
-context.setDefaultConfig({ langauge: 'ts' });
-```
-
-## 生命周期
-
-生成器插件提供了两个生命周期钩子函数用于定义生成器插件行为：
-
-- onForged：完成文件操作后的生命周期。
-
-- afterForged：onForged 钩子函数执行完成后的生命周期。
-
-## onForged
-
-在 Modern.js 工程方案生成器完成文件操作之后的钩子函数，用于完成生成器插件中的文件操作，比如添加模板文件，覆盖现有文件，删除现有文件等。
-
-对于扩展类型同时执行多个生成器插件时，将会按照声明顺序依次执行对应生成器插件的 `onForged` 操作。
-
-`onForged` 函数参数为一个回调函数，参数为 `api` 和 `input`。
-
-```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,
-  });
-})
-```
-
-`api` 上会提供生成器插件支持的文件操作相关方法。
-
-`input` 为当前用户输入内容，包含 `--config` 参数定义的，默认工程方案交互的及生成器插件定义的用户输入。
-
-当需要添加新的文件模板时，将模板文件定义到 `templates` 目录，然后通过上述 `api` 上方法进行操作即可，生成器插件默认对 `templates` 目录文件进行操作，无需再声明 `templates` 路径。
-
-## afterForged
-
-`onForged` 钩子函数执行完成后执行，这里主要用于进行安装依赖，Git 操作等。
-
-默认 Modern.js 工程方案在完成文件操作后会默认执行安装依赖及 Git 初始化，Git 初次提交等，该钩子函数可以不使用。
-
-对于自定义的生成器插件还支持 custom 类型，该类型只提供了少量最佳实践的项目配置，则需要在该钩子函数中完成安装依赖和 Git 初始化等操作。
-
-`afterForged` 函数参数也为一个回调函数，参数为 `api` 和 `input`。
-
-```ts
-  context.afterForged(
-    async (api: AfterForgedAPI, input: Record<string, unknown>) => {
-      const { packageManager } = input;
-      console.info('packageManager:', packageManager);
-      await api.install();
-    },
-  );
-```

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

@@ -1,106 +0,0 @@
----
-sidebar_position: 1
----
-
-# 介绍及创建项目
-
-## 介绍
-
-Modern.js 提供了 Web 应用、Npm 模块等工程方案，并通过使用 `@modern-js/create` 工具可以创建工程方案的初始项目模板，初始项目模板会提供基本的代码开发环境、简单的示例代码及配置等。
-
-Modern.js 提供的初始化模板具有通用性，能满足一些通用的项目开发需求。
-
-当你深度使用 Modern.js 时，必然会发现每次创建的项目都会进行一些针对自身项目的特定的相似改动，比如修改示例代码、增加一些配置、开启某些功能等。
-
-生成器插件可以帮你将这些针对个人或团队特定的改动沉淀下来，在执行 `npx @modern-js/create@latest` 只需简单的带上 `--plugin` 参数即可避免每次创建完项目都需重复性修改项目的工作。
-
-生成器插件是在 Modern.js 提供的初始化模板项目的基础上，提供对模板进行增加、删除、修改的方法，并通过快捷的方式修改 `package.json`、`modernConfig` 配置和开启功能等操作。
-
-## 创建项目
-
-使用 `@modern-js/create` 可直接创建生成器插件项目：
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? 请选择你想创建的工程类型 Npm 模块
-? 请选择项目场景 生成器插件
-? 请输入生成器插件插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请选择插件类型 extend
-? 请选择插件基础类型 Web 应用
-```
-
-创建完成后，我们可以看一下这个项目的目录结构：
-
-```bash
-.
-├── .changeset
-│   └── config.json
-├── .eslintrc.js
-├── .gitignore
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── README.md
-├── modern.config.ts
-├── package.json
-├── src
-│   ├── modern-app-env.d.ts
-│   └── index.ts
-├── templates
-│   └── .gitkeep
-└── tsconfig.json
-```
-
-项目是基于 Npm 模块项目创建的，核心是下面几个文件：
-
-```bash
-*
-├── package.json
-├── src
-│   └── index.ts
-├── templates
-│   └── .gitkeep
-```
-
-## package.json
-
-`package.json` 中除了正常的模块项目的字段外，提供了 meta 字段，用于描述生成器插件的信息。
-
-生成器插件分为两类：扩展和自定义，具体分类定义可查看[类型](/guides/topic-detail/generator/plugin/category)。
-
-```json title="package.json"
-{
-  ...,
-  "meta": {
-    "extend": "mwa"
-  }
-}
-```
-
-## src/index.ts
-
-该文件用于完成生成器插件的内容开发。
-
-```js
-import { IPluginContext, ForgedAPI } from '@modern-js/generator-plugin';
-
-export default function (context: IPluginContext) {
-  context.onForged(async (_api: ForgedAPI, _input: Record<string, unknown>) => {
-    /**
-     * todo
-     */
-  });
-}
-```
-
-该文件默认导出一个函数，函数参数为 `context`，`context` 上提供了生成器插件支持的 API 方法，可用于实现生成器插件的逻辑。`context` 提供的能力可以参考 [context](/guides/topic-detail/generator/plugin/context)。
-
-## templates
-
-`templates` 目录存在当前定制化方式的模板文件，支持 [Handlebars](https://handlebarsjs.com/) 和 [EJS](https://ejs.co/) 格式，将根据模板文件后缀使用不同的渲染引擎执行渲染，如果无后缀，将会直接复制模板文件到目标目录。
-
-如果模板文件为 `js`、`ts` 或者 `json` 文件，推荐直接使用 `.handlebars` 或者 `.ejs` 后缀，可避免项目 eslint 报错和在 Monorepo 中项目识别问题。
-
-模板中 `.gitignore` 文件和 `.npmrc` 文件在发布 npm 包时会自动删除，需要使用 `.handlebars` 或者 `.ejs` 后缀将其保留。

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

@@ -1,33 +0,0 @@
----
-sidebar_position: 3
----
-
-# 使用
-
-`@modern-js/create` 提供了 `--plugin` 参数用于运行生成器插件项目。
-
-`--plugin` 支持三种格式：
-
-## 绝对路径
-
-适用于本地开发调试，开发完成后，在生成器插件执行 `npm run build` 构建项目，然后使用下面命令即可进行测试。
-
-```bash
-npx @modern-js/create@latest --plugin <pluginPath>
-```
-
-## 相对路径
-
-适用于本地开发调试或者生成器插件项目和目标创建项目在同一个 Monorepo，无需发布 NPM 包，构建项目后，执行下面命令即可。
-
-```bash
-npx @modern-js/create@latest --plugin file:../<pluginPath>
-```
-
-## npm 包
-
-适用于生成器插件发布于 npm 上，共享生成器插件场景。
-
-```bash
-npx @modern-js/create@latest --plugin <pluginPackage>
-```