@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/guides/topic-detail/framework-plugin/implement.md

@@ -0,0 +1,188 @@
+---
+sidebar_position: 2
+---
+
+# 如何编写插件
+
+Modern.js 支持通过自定义插件的方式来实现个性化功能。
+
+## 实现插件
+
+Modern.js 插件是一个对象，对象包含以下属性：
+
+- `name`: 插件的名称，唯一标识符。
+- `setup`: 插件初始化函数，只会执行一次。setup 函数可以返回一个 Hooks 对象，Modern.js 会在特定的时机执行这些 Hooks。
+
+```ts
+const MyPlugin = {
+  name: 'my-plugin',
+
+  setup() {
+    // 执行一些初始化逻辑
+    const foo = '1';
+
+    // 返回一个 Hooks 对象
+    return {
+      afterBuild: () => {
+        // 在构建完成后执行逻辑
+      },
+    };
+  },
+};
+```
+
+### 插件类型
+
+使用 TypeScript 时，可以引入内置的 `CliPlugin` 类型，为插件提供正确的类型推导：
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+const MyPlugin: CliPlugin = {
+  name: 'my-plugin',
+
+  setup() {
+    const foo = '1';
+
+    return {
+      afterBuild: () => {
+        // 在构建完成后执行逻辑
+      },
+    };
+  },
+};
+```
+
+:::info 注
+插件可以注册丰富的 Hooks，不同的 Hook 拥有不同的模型和运行规则，详见 [Hook 模型](/docs/apis/app/runtime/plugin/hook)。
+:::
+
+### 插件配置项
+
+**建议将插件写成函数的形式**，使插件能通过函数入参来接收配置项：
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+type MyPluginOptions = {
+  foo: string;
+};
+
+const MyPlugin = (options: MyPluginOptions): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup() {
+    console.log(options.foo);
+  },
+});
+```
+
+### 插件 API
+
+插件的 setup 函数会接收一个 api 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    // 获取应用原始配置
+    const config = api.useConfigContext();
+    // 获取应用运行上下文
+    const appContext = api.useAppContext();
+    // 获取解析之后的最终配置
+    const resolvedConfig = api.useResolvedConfigContext();
+  },
+});
+```
+
+插件 API 的详细说明，请参考 [Plugin API](/docs/apis/app/runtime/plugin/plugin-api)。
+
+### 异步 setup
+
+CLI 插件的 setup 可以是一个异步函数，在初始化过程中执行异步逻辑。
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    await doSomething();
+  },
+});
+```
+
+## 添加插件
+
+自定义插件的使用方式可以查看：[plugins (框架插件)](/docs/configure/app/plugins)。下面会介绍 Modern.js 中推荐的插件实现方法。
+
+### 开发本地插件
+
+本地插件推荐写在 `config/plugin` 目录下，并通过 `export default` 导出：
+
+```ts title=config/plugin/MyPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup() {
+    // 插件初始化
+  },
+});
+```
+
+然后在 `modern.config.ts` 中注册对应的插件：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import MyPlugin from './config/plugin/MyPlugin';
+
+export default defineConfig({
+  plugins: [MyPlugin()],
+});
+```
+
+### 在 npm 上发布插件
+
+如果需要将 Modern.js 插件发布到 npm，推荐使用 Modern.js 中的模块工程方案来管理和构建，如果需要将它和使用项目管理在一起，则推荐使用 Modern.js 中的 Monorepo 工程方案管理。这里就简单地使用模块工程方案进行演示。
+
+首先创建一个空的模块工程方案项目，调整 npm 包名称：
+
+```json
+{
+  "name": "my-plugin"
+  ...
+}
+```
+
+然后新建对应的插件文件：
+
+```ts title=src/index.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup() {
+    // 插件初始化
+  },
+});
+```
+
+发布之后，安装到需要使用的项目 `pnpm add my-plugin`，这里以一个应用项目为例，然后在 `modern.config.ts` 中添加：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import MyPlugin from 'my-plugin';
+
+export default defineConfig({
+  plugins: [MyPlugin()],
+});
+```
+
+如果你发现目前 Modern.js 存在无法满足的场景，欢迎通过**编写自定义插件的方式**来一起建设 Modern.js 生态。

package/zh/guides/topic-detail/framework-plugin/relationship.md

@@ -0,0 +1,119 @@
+---
+sidebar_position: 3
+---
+
+# 插件之间的关系
+
+Modern.js 的插件配置对象提供了一系列的字段，用于控制插件顺序、互斥等能力，可用的字段如下：
+
+- `name`: `string`，设置当前插件的名称。
+- `pre`: `string[]`，这些插件最终会调整到当前插件前面。
+- `post`: `string[]`，这些插件最终会调整到当前插件后面。
+- `rivals`: `string[]`，互斥插件，遇到这些插件时会报错。
+- `required`: `string[]`，必需插件，插件列表中没有对应的插件时会报错。
+- `usePlugin`: `CliPlugin[]`，注册其他插件。
+
+通过以上参数可以实现插件的前置、后置、互斥、必需等逻辑。
+
+## 插件排序
+
+Modern.js 的插件通过 `pre`、`post` 参数来实现了插件排序的功能。
+
+### 前置插件
+
+默认情况下，插件会按照添加顺序依次执行，通过 `pre` 字段可以声明前置执行的插件。
+
+比如有下面两个插件：
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  pre: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `pre` 字段中配置了 `foo` 插件，因此 `foo` 插件一定会在 `bar` 插件之前执行。
+
+### 后置插件
+
+同样的，通过 `post` 字段可以声明后置执行的插件。
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  post: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `post` 字段中配置了 `foo` 插件，因此 `foo` 插件一定会在 `bar` 插件之后执行。
+
+## 互斥插件
+
+通过 `rivals` 字段可以声明插件间的互斥关系。
+
+有下面两个插件：
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  rivals: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `rivals` 字段中配置了 `foo` 插件，因此同时添加了 `foo` 插件和 `bar` 插件就会报错。
+
+## 必需插件
+
+通过 `required` 字段可以声明插件间的依赖关系。
+
+有下面两个插件：
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  required: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `required` 字段中配置了 `foo` 插件，因此使用 `bar` 插件时，如果未配置 `foo` 插件就会报错。
+
+## 注册插件
+
+当插件之间存在依赖关系时，我们也可以在一个插件中通过 `usePlugin` 主动注册另一个插件：
+
+```ts title=foo.ts
+const foo = () => ({
+  name: 'plugin-foo',
+});
+
+const bar = () => ({
+  name: 'plugin-bar',
+  usePlugin: [foo()],
+});
+```
+
+当使用者配置了 `bar` 插件时，`foo` 插件也会自动注册生效，使用者就不需要去额外注册 `foo` 插件了。

package/zh/guides/topic-detail/generator-plugin/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "自定义生成器插件",
+  "position": 7
+}

package/zh/guides/topic-detail/generator-plugin/abstract.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+---
+
+# 为什么需要生成器插件
+
+Modern.js 提供了应用(MWA)、模块和 Monorepo 三种工程方案，并通过使用 `@modern-js/create` 工具可以创建三种工程方案的初始项目模板，初始项目模板会提供基本的代码开发环境、简单的示例代码及配置等。
+
+Modern.js 提供的初始化模板具有通用性，能满足一些通用的项目开发需求。
+
+当你深度使用 Modern.js 时，必然会发现每次创建的项目都会进行一些针对自身项目的特定的相似改动，比如修改示例代码、增加一些配置、开启某些功能等。
+
+生成器插件可以帮你将这些针对个人或团队特定的改动沉淀下来，在执行 `npx @modern-js/create` 只需简单的带上 `--plugin` 参数即可避免每次创建完项目都需重复性修改项目的工作。
+
+生成器插件是在 Modern.js 提供的初始化模板项目的基础上，提供对模板进行增加、删除、修改的方法，并通过快捷的方式修改 `package.json`、`modernConfig` 配置和开启功能等操作。
+
+生成器插件提供了两种定制化方式：
+
+1. 扩展工程方案：直接对默认提供的三大工程方案进行定制化
+
+2. 创建工程方案场景：基于默认的三大工程方案创建对应的工程方案场景
+
+接下来将会逐步介绍如何使用和开发生成器插件。

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

@@ -0,0 +1,120 @@
+---
+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](/docs/apis/generator/plugin/introduce)。
+
+### 自定义输入
+
+- addInputBefore
+
+在默认的输入前添加输入，比如在`选择包管理工具`问题前添加问题，具体 Modern.js 每个问题的配置可查看[生成器配置](/docs/configure/generator/introduce)。
+
+```ts
+context.addInputBefore('packageManager', {
+    key: 'test',
+    name: '测试输入',
+    type: 'input'
+})
+```
+
+- setInput
+
+设置已经存在问题的属性
+
+```ts
+context.setInput('test', 'type', 'radio')
+context.setInput('test', 'options', [{ key: 'option1', name: '选项一' }])
+```
+
+### onForged
+
+工程方案类型文件相关操作执行完成后钩子，多个扩展产检将按照 `plugin` 参数顺序依次执行其 `onForged` 函数。
+
+`onForged` 参数是一个回调函数，函数参数为 `api` 和 `input`。
+
+`api` 上会提供一些文件操作相关的方法，可在该钩子中对当前的模板文件进行操作。
+
+`input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
+
+当需要新的模板文件时，可直接在 `templates` 目录添加，在 `onForged` 函数中可直接对 `templates` 目录文件进行操作，比如下方的 `addFile` 中 `templateFile` 参数就为 `templates` 目录下的文件。这里不需要显示的声明 `templates`，直接写相对于 `templates` 的相对路径即可。
+
+`onForged` 中支持的 API 函数也可参考 [生成器插件API](/docs/apis/generator/plugin/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](/docs/apis/generator/plugin/hook/afterForged)。

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

@@ -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/micro-frontend/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "微前端",
+  "position": 2
+}

package/zh/guides/topic-detail/micro-frontend/communicate.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 3
+title: 主子应用通信
+---
+
+## props 通信
+
+Modern.js 中，会将子应用包裹成一个 React 组件，直接通过给 React 组件传递 `props` 即可实现主应用和子应用通信的目的。
+
+```tsx title=主应用：App.tsx
+function App() {
+  const { Dashboard } = useModuleApps();
+  const [count, setCount] = useState(0);
+
+  return <div>
+    <Dashboard count={count} />
+    <button onClick={() => setCount(count + 1)}>add</button>
+  </div>;
+}
+```
+
+```tsx title=子应用：App.tsx
+function App(props) {
+  console.log(props);
+
+  return ...
+}
+```
+
+子应用将会打印 `{count: 0}`。
+
+当主应用点击 `add` 按钮，`count` 状态更新的时候，子应用也会响应到最新的 `props` 数据，并重新渲染。
+
+## 使用 Model 通信
+
+
+:::tip 提示
+近期上线，敬请期待。
+:::