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

package/zh/guides/topic-detail/generator/plugin/develop.mdx

@@ -0,0 +1,125 @@
+---
+sidebar_position: 3
+---
+
+# 如何开发生成器插件
+
+## 创建项目
+
+Modern.js 提供了创建生成器插件项目的生成器插件用于创建项目，可直接执行以下命令创建:
+
+```bash
+npx @modern-js/create plugin --plugin @modern-js/generator-plugin-plugin
+```
+
+插件类型不同，会提问不同的问题，可根据需求选择插件类型
+
+### 扩展类型
+
+```
+? 请选择你想创建的工程类型 模块
+? 请选择项目场景 生成器插件
+? 插件包名 plugin
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 插件类型 扩展
+? 插件基础类型 应用
+```
+
+### 自定义类型
+
+```
+? 请选择你想创建的工程类型 模块
+? 请选择项目场景 生成器插件
+? 插件包名 plugin
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 插件类型 自定义
+? 插件关键字 mobile-app
+? 插件展示名称 移动应用
+? 插件基础类型 应用
+```
+
+创建项目命令执行完成后，会对应的生成一个开发生成器插件的项目，`package.json` 中也会根据你的选择对应的生成 `meta` 信息。
+
+:::info
+生成器插件开发可参考 `@modern-js/generator-plugin-plugin` [源码地址](https://github.com/modern-js-dev/modern.js/tree/main/packages/generator/plugins/generator-plugin)
+
+:::
+
+## 开发插件逻辑
+
+在 `src/index.ts` 中完成插件逻辑开发。
+
+插件默认导出一个函数，函数参数为 `context`，`context` 上提供一些方法可直接对当前项目进行操作。
+
+简单介绍一下提供的方法，完整的 API 列表可查看[生成器插件 API](/guides/topic-detail/generator/plugin/api/introduce)。
+
+### 自定义输入
+
+- addInputBefore
+
+在默认的输入前添加输入，比如在`选择包管理工具`问题前添加问题，具体 Modern.js 每个问题的配置可查看[工程方案配置](/guides/topic-detail/generator/config/common)。
+
+```ts
+context.addInputBefore('input2', {
+  type: 'object',
+  properties: {
+    'input1.2': {
+      type: 'string',
+      title: 'input1.2',
+    },
+  },
+});
+```
+
+- setInput
+
+设置已经存在问题的属性
+
+```ts
+context.setInput('test', 'type', 'number');
+context.setInput('test', 'enum', [{ value: 'option1', label: '选项一' }]);
+```
+
+### onForged
+
+工程方案类型文件相关操作执行完成后钩子，多个扩展产检将按照 `plugin` 参数顺序依次执行其 `onForged` 函数。
+
+`onForged` 参数是一个回调函数，函数参数为 `api` 和 `input`。
+
+`api` 上会提供一些文件操作相关的方法，可在该钩子中对当前的模板文件进行操作。
+
+`input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
+
+当需要新的模板文件时，可直接在 `templates` 目录添加，在 `onForged` 函数中可直接对 `templates` 目录文件进行操作，比如下方的 `addFile` 中 `templateFile` 参数就为 `templates` 目录下的文件。这里不需要显示的声明 `templates`，直接写相对于 `templates` 的相对路径即可。
+
+`onForged` 中支持的 API 函数也可参考 [生成器插件 API](/guides/topic-detail/generator/plugin/api/hook/onForged)。
+
+```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,
+  });
+});
+```
+
+### afterForged
+
+`onForged` 函数执行完成后钩子，这里主要可进行安装依赖，Git 操作等。
+
+如果你的工程方案是基于 Modern.js 提供的三种工程方案进行的，这个钩子函数是可以不需要的。默认的工程方案中会自动包含安装依赖、提交代码逻辑。
+
+生成器插件还支持了一种自定义的 `custom` 类型，这种类型只提供了少量的开发层面的最佳实践的代码，比如 `.gitignore`、`.editorConfig` 等文件，这时则需要在 `afterForged` 函数中手动补充安装依赖和 Git 操作逻辑。
+
+`afterForged` 参数也是一个回调函数，函数参数为 `api` 和 `input`。
+
+`api` 上会提供一些 npm、Git 等方法，可在该钩子中进行安装依赖，Git 操作。
+
+`input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
+
+`afterForged` 中支持的 API 函数也可参考 [生成器插件 API](/guides/topic-detail/generator/plugin/api/hook/afterForged)。

package/zh/guides/topic-detail/generator/plugin/use.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+---
+
+# 如何使用生成器插件
+
+`@modern-js/create` 提供了 `--plugin` 参数用于声明使用的生成器插件。
+
+你可直接执行下面命令使用生成器插件：
+
+```bash
+npx @modern-js/create --plugin <pluginName>
+```
+
+plugin 参数支持声明多次，代表同时使用多个生成器插件。
+
+## 生成器插件分类
+
+生成器插件分为两种：
+
+1. 扩展工程方案：直接对默认提供的三大工程方案进行定制化。
+
+2. 创建工程方案场景：基于默认的三大工程方案创建对应的工程方案场景。
+
+### 类型定义
+
+生成器插件的分类通过 `package.json` 中的 `meta` 信息提供。
+
+#### 扩展工程方案
+
+```json
+{
+  "meta": {
+    "extend": "mwa" // 三个工程方案分别对应 mwa、module、 monorepo
+  }
+}
+```
+
+#### 创建工程方案场景
+
+```json
+{
+  "meta": {
+    "key": "new_solution",
+    "name": "新工程方案",
+    "type": "mwa" // 除了三大工程方案，这里类型还支持自定义(custom)类型，后面会详细介绍
+  }
+}
+```
+
+### 执行时机
+
+不同类型的定制工程方案的执行时机是不同的。
+
+#### 扩展工程方案
+
+扩展工程方案类型的生成器插件会在选择对应 extend 的工程方案后按照 plugin 参数的声明顺序依次执行。
+
+#### 创建工程方案场景
+
+创建工程方案场景的生成器插件会在选择对应类型的工程方案之后出现选择场景的选项，选项列表包括当前默认的工程方案场景和插件定义的工程方案场景，选择对应的场景，将会执行对应的生成器插件。

package/zh/guides/topic-detail/generator/project.mdx

@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+---
+
+# 项目生成器
+
+Modern.js 提供了 `@modern-js/create` 作为项目生成器用于进行 Modern.js 工程方案项目创建。
+
+## 使用
+
+不需要全局安装 `@modern-js/create`，直接使用 npx 执行该工具即可：
+
+```bash
+npx @modern-js/create [projectDir]
+```
+
+:::info
+使用 npx 可以每次获取最新版本的 `@modern-js/create`。
+
+:::
+
+## 参数
+
+### [projectDir]
+
+项目目录名称。
+
+执行上述命令时，默认会在当前目录创建 `projectDir` 文件夹，并在该文件夹下初始化项目。该参数为空时，将会在当前目录直接生成初始化项目。
+
+### --version
+
+获取 `@modern-js/create` 工具版本。
+
+```bash
+$ npx @modern-js/create --version
+
+[INFO] @modern-js/create v2.0.0
+```
+
+### --lang
+
+指定执行语言，支持 `zh` 和 `en`。
+
+默认情况下，`@modern-js/create` 会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者想手动指定语言，可以使用该参数。
+
+### -c, --config
+
+指定项目默认配置。
+
+默认情况下，`@modern-js/create` 在执行过程中会出现选择语言、包管理工具等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
+
+该字段为 JSON 字符串，例如需执行包管理工具时：
+
+```bash
+npx @modern-js/create --config '{"packageManager": "pnpm"}'
+```
+
+具体配置信息可查看[工程方案配置](/guides/topic-detail/generator/config/common)。
+
+### --no-need-install
+
+默认情况下，`@modern-js/create` 在创建项目完成后会自动安装依赖，使用该参数可以忽略安装依赖步骤。
+
+### --dist-tag \<distTag\>
+
+指定生成器及 Modern.js 相关依赖版本。
+
+`@modern-js/create` 执行过程中会执行更小的微生成器，使用该参数可以执行执行的微生成器的版本号和对应的安装 Modern.js 相关依赖的版本号。
+
+### --registry \<registry/>
+
+执行获取生成器及 npm 包的 npm registry。
+
+### --debug
+
+显示生成器执行过程中的调试日志信息。
+
+### --mwa
+
+一键创建应用工程方案项目。
+
+使用该参数后，`@modern-js/create` 将会使用配置默认值创建应用项目。
+
+### --module
+
+一键创建模块工程方案项目。
+
+使用该参数后，`@modern-js/create` 将会使用配置默认值创建模块项目。
+
+### --monorepo
+
+一键创建 Monorepo 工程方案项目。
+
+使用该参数后，`@modern-js/create` 将会使用配置默认值创建 Monorepo 项目。
+
+### --plugin \<plugin\>
+
+指定生成器插件。
+
+Modern.js 支持使用生成器插件定制 Modern.js 默认的工程方案类型或者添加工程方案类型场景，该参数用户指定定制的生成器插件。
+
+关于定制生成器插件可以参考[开发生成器插件](/guides/topic-detail/generator/plugin/abstract)。
+
+### --generator \<generator\>
+
+指定微生成器。
+
+默认情况下 `@modern-js/create` 会执行 Modern.js 框架内置的微生成器，如果你需要执行定制的微生成器，又需要使用 `npx @modern-js/create` 的姿势，可直接使用该参数。
+
+关于定制微生成器可以参考[开发微生成器](/guides/topic-detail/generator/codesmith/introduce)。
+
+### --packages \<packages\>
+
+创建项目是指定特定包版本依赖。
+
+在创建项目时如果有需要指定特定包版本，可以使用该参数。该参数会在项目根目录的 `package.json` 中配置 `pnpm.overrides`(包管理工具选择 pnpm) 或者 `resolutions` 锁定包版本号。
+
+该参数值为 JSON 字符串。

package/zh/guides/topic-detail/micro-frontend/c01-introduction.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+title: 微前端介绍
+---
+# 微前端介绍
+
+微前端是一种类似于微服务的架构，是一种由独立交付的多个前端应用组成整体的架构风格，将前端应用分解成一些更小、更简单的能够独立开发、测试、部署的应用，而在用户看来仍然是内聚的单个产品。
+
+它主要解决了两个问题：
+
+- 随着项目迭代应用越来越庞大，难以维护。
+- 跨团队或跨部门协作开发项目导致效率低下的问题。
+
+## 微前端关键词
+
+在微前端研发模式中，应用会被分成 **主应用**、和 **子应用**。
+
+- 主应用：微前端项目的基座工程，所有子应用都会由它来加载。
+- 子应用：独立开发、独立部署的应用，最终会被主应用加载。
+
+## 功能简介
+
+- 基于 [Garfish](https://www.garfishjs.org/guide)
+- 生成器支持微前端应用
+- 支持 React 组件式引用微前端子应用
+- 支持 loading
+- 支持主应用线上、子应用线下调试模式
+
+可以在 [体验微前端](/guides/topic-detail/micro-frontend/c02-development) 一节学习如何开发微前端主子应用。

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

@@ -0,0 +1,189 @@
+---
+sidebar_position: 2
+title: 体验微前端
+---
+# 体验微前端
+
+通过本章你可以了解到：
+
+- 如何创建微前端项目的主应用、子应用。
+- 微前端项目开发的基本流程。
+
+## 创建应用
+
+在这次的实践中，我们需要创建三个应用，分别为 1 个主应用，2 个子应用：
+
+- main 主应用
+- dashboard 子应用
+- table 子应用
+
+### 创建 main 主应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir main && cd main
+npx @modern-js/create
+```
+
+import DefaultMWAGenerate from "@site-docs/components/default-mwa-generate";
+
+<DefaultMWAGenerate />
+
+完成项目创建后我们可以通过 `pnpm run new` 来开启 `微前端` 功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+
+接下来，让我们注册微前端插件并添加开启微前端主应用，并增加子应用列表：
+
+import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
+
+<EnableMicroFrontend />
+
+import MicroRuntimeConfig from "@site-docs/components/micro-runtime-config";
+
+<MicroRuntimeConfig />
+
+### 创建 dashboard 子应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir dashboard && cd dashboard
+npx @modern-js/create
+```
+
+按照如下选择，生成项目：
+
+<DefaultMWAGenerate/>
+
+我们执行 `pnpm run new` 来开启 `微前端` 功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+
+接下来，让我们注册微前端插件并修改 `modern.config.ts`，添加微前端子应用的配置 `deploy.microFrontend`：
+
+```js title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import garfishPlugin from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  deploy: {
+    microFrontend: true,
+  },
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+### 创建 table 子应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir table && cd table
+npx @modern-js/create
+```
+
+按照如下选择，生成项目：
+
+<DefaultMWAGenerate/>
+
+我们执行 `pnpm run new` 来开启 `微前端`：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+
+接下来，让我们注册微前端插件并修改 `modern.config.ts`，添加微前端子应用的配置 `deploy.microFrontend`：
+
+```js title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import garfishPlugin from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  deploy: {
+    microFrontend: true,
+  },
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+## 添加代码
+
+### main 主应用
+
+删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+
+```tsx
+import { Link } from '@modern-js/runtime/router';
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+
+const App = () => {
+  const { DashBoard, TableList } = useModuleApps();
+  return (
+    <div>
+      <div>
+        <Link to="/dashboard">Dashboard</Link> &nbsp;
+        <Link to="/table">Table</Link>
+      </div>
+      <Route path="/dashboard">
+        <DashBoard />
+      </Route>
+      <Route path="/table">
+        <TableList />
+      </Route>
+    </div>
+  );
+};
+
+export default App;
+```
+
+### dashboard 子应用
+
+删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+
+```tsx
+export default () => <div>Dashboard Page</div>;
+```
+
+### table 子应用
+
+删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+
+```tsx
+export default () => <div>Table Page</div>;
+```
+
+## 调试
+
+按顺序在 `main`、 `dashboard`、 `table` 目录执行 `pnpm run dev` 命令启动应用：
+
+- main - `http://localhost:8080`
+- dashboard - `http://localhost:8081`
+- table - `http://localhost:8082`
+
+访问主应用地址 `http://localhost:8080`，效果如下：
+
+![demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/micro-demo.gif)
+
+在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](./c03-main-app.md)
+
+## 常见问题
+
+自查手册: https://www.garfishjs.org/issues/