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

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

@@ -0,0 +1,125 @@
+---
+sidebar_position: 3
+---
+
+# How to develop generator plugins
+
+## Create project
+
+Modern.js provides a generator plugin to create a generator plugin project, you can directly execute the following command to create:
+
+```bash
+npx @modern-js/create plugin --plugin @modern-js/generator-plugin-plugin
+```
+
+Different plugin types will ask different questions. You can choose the plugin type according to your needs.
+
+### Extension type
+
+```
+? Please select the solution you want to create Module Solution
+? Please select the scene you want to create 生成器插件
+? Plugin Package Name plugin
+? Development Language TS
+? Package Management Tool pnpm
+? Plugin Type extend
+? Plugin Base Type MWA Solution
+```
+
+### Customized type
+
+```
+? Plugin Package Name plugin
+? Development Language TS
+? Package Management Tool pnpm
+? Plugin Type custom
+? Plugin Key mobile-app
+? Plugin Show Name Mobile App
+? Plugin Base Type MWA Solution
+```
+
+After the execution of the create project command is completed, a project for developing the generator plugin will be generated accordingly, and the `meta` information will also be generated according to your selection in the `package.json`.
+
+:::info
+For generator plugin development, please refer to `@modern-js/generator-plugin-plugin`. [Source Code](https://github.com/modern-js-dev/modern.js/tree/main/packages/generator/plugins/generator-plugin)
+
+:::
+
+## Develop plugin logic
+
+Complete plugin logic development in `src/index.ts`.
+
+The plugin exports a function by default, the function parameter is `context`, and some methods are provided on `context` to directly operate on the current project.
+
+A brief introduction to the provided methods, the complete API list viewable [Generator Plugin API](/guides/topic-detail/generator/plugin/api/introduce).
+
+### Customize input
+
+- addInputBefore
+
+Add input before the default input, such as adding questions before the `Select package management tool` question.
+
+Specific Modern.js configuration viewable for each problem [Project Solution Configuration](/guides/topic-detail/generator/config/common).
+
+```ts
+context.addInputBefore('input2', {
+  type: 'object',
+  properties: {
+    'input1.2': {
+      type: 'string',
+      title: 'input1.2',
+    },
+  },
+});
+```
+
+- setInput
+
+Set attributes of existing problems.
+
+```ts
+context.setInput('test', 'type', 'number');
+context.setInput('test', 'enum', [{ value: 'option1', label: '选项一' }]);
+```
+
+### onForged
+
+After the implementation of the hook related operations of the project plan type file is completed, multiple extended inspection will execute its `onForged` function in sequence according to the `plugin` parameter order.
+
+The `onForged` parameter is a callback function, and the function parameters are `api` and `input`.
+
+Some file manipulation related methods are provided on the `api`, which can operate on the current template file in this hook.
+
+`input` is the current user input, which can be used to obtain the current input information and configuration information of the user.
+
+When you need a new template file, you can add it directly in the `templates` directory. In the `onForged` function, you can directly operate the `templates` directory file. For example, the `templateFile` parameter in the `addFile` below is the file in the `templates` directory. There is no need to display the declaration `templates` here, just write the relative path relative to `templates`.
+
+API functions supported in `onForged` can also be found in [Generator Plugin 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
+
+After the `onForged` function is executed, it can mainly install dependencies, Git operations, etc.
+
+If your project plan is based on the three projects provided by the Modern.js, this hook function may not be required. The default project plan will automatically include the installation dependency and commit code logic.
+
+The generator plugin also supports a customized `custom` type, which only provides a small amount of development-level best practice code, such as `.gitignore`, `editorConfig` and other files. In this case, you need to manually supplement the installation dependency and Git operation logic in the `afterForged` function.
+
+The `afterForged` parameter is also a callback function, and the function parameters are `api` and `input`.
+
+The `api` will provide some npm, Git and other methods, which can install dependency and Git operations in this hook.
+
+`input` is the current user input, which can be used to obtain the current input information and configuration information of the user.
+
+The API functions supported in `afterForged` can also be found in [Generator Plugin API] (/docs/guides/topic-detail/generator/plugin/api/hook/afterForged).

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

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+---
+
+# How to use the generator plugin
+
+`@modern-js/create` provides the `--plugin` parameter to declare the generator plugin used.
+
+You can use the generator plugin directly by executing the following command:
+
+```bash
+npx @modern-js/create --plugin <pluginName>
+```
+
+The plugin parameter supports multiple declarations, which means that multiple generator plugins are used at the same time.
+
+## Classification
+
+There are two types of generator plugins:
+
+1. Extended engineering: directly customize the three major engineering provided by default.
+
+2. Create engineering scenes: Create corresponding engineering scenes based on the default three major engineering schemes.
+
+### Type definition
+
+The classification of the generator plugin is provided by the meta information in the `package.json`.
+
+#### Extended engineering
+
+```json
+{
+  "meta": {
+    "extend": "mwa" // The three engineering is mwa, module, monorepo
+  }
+}
+```
+
+#### Create engineering scenes
+
+```json
+{
+  "meta": {
+    "key": "new_solution",
+    "name": "New Solution",
+    "type": "mwa" // In addition to the three major engineering solutions, the type here also supports the customize (custom) type
+  }
+}
+```
+
+### Execution timing
+
+The execution timing of different types of custom engineering solutions is different.
+
+#### Extended engineering
+
+The generator plugin of the extended engineering type will execute in sequence according to the declaration order of the plugin parameter after selecting the corresponding extended project scheme.
+
+#### Create engineering scenes
+
+The generator plugin that create engineering scenes will have the option to select the scene after selecting the project solution type. The option list includes the current default project scenes and the project scenes defined by the plugin. If you select the corresponding scene, the corresponding generator will be executed plugin.

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

@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+---
+
+# Project Generator
+
+Modern.js provides `@modern-js/create` as a project generator for Modern.js project creation.
+
+## Use
+
+There is no need to install `@modern-js/create` globally, just execute the tool directly with npx:
+
+```bash
+npx @modern-js/create [projectDir]
+```
+
+:::info
+Use npx to get the latest version of `@modern-js/create` every time.
+
+:::
+
+## Params
+
+### [projectDir]
+
+Project directory name.
+
+When executing the above command, the `projectDir` folder will be created in the current directory by default, and the initialization project will be in this folder. When this parameter is empty, the initialization project will be directly generated in the current directory.
+
+### --version
+
+Get the `@modern-js/create` tool version.
+
+```bash
+$ npx @modern-js/create --version
+
+[INFO] @modern-js/create v2.0.0
+```
+
+### --lang
+
+Specifies the execution language, supports `zh` and `en`.
+
+By default, `@modern-js/create` will automatically identify the user's system language, choose to use Chinese or English, if the recognition fails or you want to specify the language manually, you can use this parameter.
+
+### -c, --config
+
+Specifies the project default configuration.
+
+By default, `@modern-js/create` will have interaction problems such as language selection and package management tools during execution. When you need to specify these configuration contents in advance, you can pass in this field.
+
+This field is a JSON character string, for example when running a package management tool:
+
+```bash
+npx @modern-js/create --config '{"packageManager": "pnpm"}'
+```
+
+Specific configuration information viewable [Project Configuration](/guides/topic-detail/generator/config/common).
+
+### --no-need-install
+
+By default, `@modern-js/create` automatically installs dependency after the project is created, use this parameter to ignore the install dependency step.
+
+### --dist-tag \<distTag\>
+
+Specifies the generator and Modern.js dependency versions.
+
+A smaller micro-generator will be executed during the execution of `@modern-js/create`, and the version number of the micro-generator that can be executed with this parameter and the version number of the corresponding installation Modern.js related dependencies.
+
+### --registry \<registry/>
+
+Execute the npm registry to get the generator and npm packages.
+
+### --debug
+
+Displays debug log information during generator execution.
+
+### --mwa
+
+One-click to create an application engineering solution project.
+
+With this parameter, `@modern-js/create` will create the application project with the configuration default value.
+
+### --module
+
+One-click to create a module engineering solution project.
+
+With this parameter, `@modern-js/create` will create the module project with the configuration default value.
+
+### --monorepo
+
+One-click to create a Monorepo engineering solution project.
+
+With this parameter, `@modern-js/create` will create the Monorepo project with the configuration default value.
+
+### --plugin \<plugin\>
+
+Specifies the generator plugin.
+
+Modern.js support the use of the generator plug-in custom Modern.js the default project type or add the project type scenes, the parameter user specifies the customized generator plugin.
+
+For custom generator plugins, please refer to [Development Generator Plugin](/guides/topic-detail/generator/plugin/abstract).
+
+### --generator \<generator\>
+
+Specifies the microgenerator.
+
+By default, `@modern-js/create` will execute the microgenerator Modern.js framework build-in. If you need to execute a customized microgenerator, and you need to use the posture of `npx @modern-js/create`, you can use this parameter directly.
+
+For custom microgenerators, please refer to [Develop Microgenerator](/guides/topic-detail/generator/codesmith/introduce).
+
+### --packages \<packages\>
+
+A project is created by specifying a specific package version dependency.
+
+If you need to specify a specific package version when creating a project, you can use this parameter. This parameter will lock the package version number in the `package.json` of the project root directory by configuration `pnpm.overrides` (package management tool selects pnpm) or `resolutions`.
+
+The parameter value is a JSON character string.

package/en/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/en/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/