@modern-js/main-doc 2.21.0 → 2.22.0

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

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

@@ -0,0 +1,105 @@
+---
+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 Web 应用和 Npm 模块工程方案都存在一些默认的 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

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

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

package/docs/zh/guides/topic-detail/micro-frontend/c02-development.mdx

@@ -35,7 +35,7 @@ import DefaultMWAGenerate from "@site-docs/components/default-mwa-generate";
 
 ```bash
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「微前端」模式
+? 请选择功能名称 启用「微前端」模式
 ```
 
 接下来，让我们注册微前端插件并添加开启微前端主应用，并增加子应用列表：
@@ -115,7 +115,7 @@ npx @modern-js/create@latest
 
 ```bash
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「微前端」模式
+? 请选择功能名称 启用「微前端」模式
 ```
 
 接下来，让我们注册微前端插件并添加开启微前端主应用，并增加子应用列表：
@@ -145,7 +145,7 @@ npx @modern-js/create@latest
 
 ```bash
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「微前端」模式
+? 请选择功能名称 启用「微前端」模式
 ```
 
 接下来，让我们注册微前端插件并修改 `modern.config.ts`，添加微前端子应用的配置 `deploy.microFrontend`：
@@ -197,7 +197,7 @@ npx @modern-js/create@latest
 
 ```bash
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「微前端」模式
+? 请选择功能名称 启用「微前端」模式
 ```
 
 接下来，让我们注册微前端插件并修改 `modern.config.ts`，添加微前端子应用的配置 `deploy.microFrontend`：

package/docs/zh/guides/topic-detail/model/test-model.mdx

@@ -10,7 +10,7 @@ title: 测试 Model
 
 ```bash
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「单元测试 / 集成测试」功能
+? 请选择功能名称 启用「单元测试 / 集成测试」功能
 ```
 
 即可开启测试功能支持。

package/docs/zh/tutorials/first-app/c03-css.mdx

@@ -115,7 +115,7 @@ Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind
 
 ```bash
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用 Tailwind CSS 支持
+? 请选择功能名称 启用 「Tailwind CSS」 支持
 ```
 
 在 `modern.config.ts` 中注册 Tailwind 插件:

package/docs/zh/tutorials/first-app/c08-entries.mdx

@@ -15,7 +15,7 @@ title: 添加应用入口
 
 ```bash
 ? 请选择你想要的操作 创建工程元素
-? 创建工程元素 新建「应用入口」
+? 请选择创建元素类型 新建「应用入口」
 ? 请填写入口名称 (entry) landing-page
 ```
 

package/modern.config.ts

@@ -130,7 +130,8 @@ export default defineConfig({
       ],
     },
     route: {
-      exclude: ['scripts/**', '**/components/**'],
+      // exclude document fragments from routes
+      exclude: ['scripts/**', '**/zh/components/**', '**/en/components/**'],
     },
     builderConfig: {
       output: {

package/package.json

@@ -15,13 +15,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.21.0",
+  "version": "2.22.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.21.0"
+    "@modern-js/builder-doc": "^2.22.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -33,9 +33,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.21.0",
-    "@modern-js/doc-tools": "2.21.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.21.0"
+    "@modern-js/builder-doc": "2.22.0",
+    "@modern-js/doc-tools": "2.22.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.22.0"
   },
   "scripts": {
     "dev": "modern dev",

package/docs/en/apis/app/hooks/api/framework/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "框架写法",
-  "position": 2
-}

package/docs/en/apis/app/hooks/api/framework/lambda.mdx

@@ -1,57 +0,0 @@
----
-title: lambda/*.[tj]s
-sidebar_position: 1
----
-# lambda/*.[tj]s
-
-Declaring API routing in BFF framework mode. Except [some files](/apis/app/hooks/api/framework/lambda#allow-list), files in `api/` are registered as routes.
-
-:::info
-use `api/` need execute new command to enable the 「BFF」 feature.
-
-:::
-
-:::tip
-this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
-
-:::
-
-## Routing Rule
-
-### Default Route
-
-The files named `index` will be upper level routing:
-
-- `api/lambda/index.ts` -> `$BASENAME/`
-- `api/lambda/user/index.ts` -> `$BASENAME/user`
-
-### Multi Level Route
-
-The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
-
-- `api/lambda/hello.ts` -> `$BASENAME/hello`
-- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Route
-
-Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
-
-- `api/lambda/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-- `api/lambda/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
-- `api/lambda/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
-
-the `$BASENAME` can be configured in `modern.config.js`, the default value is `/api`.
-
-### Allow List
-
-By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
-
-- file name start with `_`, for example: `_utils.ts`.
-- files in directory that name start with `_`, for example: `_utils/index.ts`、`_utils/cp.ts`.
-- test files, for example: `foo.test.ts`.
-- TypeScript define files, for example: `hello.d.ts`.
-- files in `node_module`.
-
-## Define Function
-
-the same as [Define Function](/apis/app/hooks/api/functions/api#define-function).

package/docs/en/apis/app/hooks/api/functions/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "函数写法",
-  "position": 1
-}

package/docs/en/apis/app/hooks/api/functions/api.mdx

@@ -1,81 +0,0 @@
----
-title: '**/*.[tj]s'
-sidebar_position: 1
----
-# **/*.[tj]s
-
-Declaring API routing in BFF function mode. Except [some files](/apis/app/hooks/api/functions/api#allow-list), files in `api/` are registered as routes.
-
-:::info
-use `api/` need execute new command to enable the 「BFF」 feature.
-
-:::
-
-:::tip
-this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
-
-:::
-
-## Routing Rule
-
-### Default Route
-
-The files named `index` will be upper level routing:
-
-- `api/index.ts` -> `$BASENAME/`
-- `api/user/index.ts` -> `$BASENAME/user`
-
-### Multi Level Route
-
-The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
-
-- `api/hello.ts` -> `$BASENAME/hello`
-- `api/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Route
-
-Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
-
-- `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-- `api/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
-- `api/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
-
-the `$BASENAME` can be configured in `modern.config.js`, the default value is `/api`.
-
-### Allow List
-
-By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
-
-- file name start with `_`, for example: `_utils.ts`.
-- files in directory that name start with `_`, for example: `_utils/index.ts`、`_utils/cp.ts`.
-- test files, for example: `foo.test.ts`.
-- TypeScript define files, for example: `hello.d.ts`.
-- files in `node_module`.
-
-## Define Function
-
-In addition to the above routing rules, the function definition and export in the code also have conventions.
-
-function need named exports, and the name of the exported function is the HTTP Method:
-
-```ts
-export const get = async () => {
-  return {
-    name: 'Modern.js',
-    desc: 'Modern web Solutions',
-  };
-};
-```
-
-Export the function like above will generate a `POST` interface.
-
-App support 9 Method definitions: `GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`. so App can use these name as function export nane.
-
-The name is insensitive, whaterver `get`、`Get`、`GEt`、`GET`, can be accurately identified. And default export, `export default xxx` will be `Get` method.
-
-because `delete` is a keyword in JavaScript, use `del` or `DELETE` instead.
-
-Multiple functions of different Methods can be defined in one file, but if multiple functions of the same Method are defined, only the first can work.
-
-:::info
-It should be noted that the defined functions should be asynchronous, which is related to the type when the function is called.

package/docs/en/apis/app/hooks/api/functions/app.mdx

@@ -1,12 +0,0 @@
----
-title: _app.[tj]s
-sidebar_position: 3
----
-# _app.[tj]s
-
-in BFF function mode, this file can add middleware before [BFF 函数](/apis/app/hooks/api/functions/api).
-
-:::note
-For detail, see [hook](/apis/app/runtime/bff/hook)
-
-:::

package/docs/en/apis/app/hooks/api/functions/common.mdx

@@ -1,9 +0,0 @@
----
-title: '**/_*.[tj]s, _*/**'
-sidebar_position: 2
----
-# **/_*.[tj]s, _*/**
-
-under BFF function mode, these files are not registered as routes.
-
-Any files that not routes, but required in the project can be named in this way.

package/docs/en/guides/topic-detail/generator/codesmith/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Develop microgenerator",
-  "position": 5
-}

package/docs/en/guides/topic-detail/generator/codesmith/api/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "API",
-  "position": 5
-}