@modern-js/main-doc 2.7.0 → 2.9.0

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

@@ -1,248 +0,0 @@
----
-title: 如何编写插件
-sidebar_position: 3
----
-# 如何编写插件
-
-上一小节介绍了 Modern.js 插件的 Hook 模型，这一小节介绍如何编写插件。
-
-## 实现插件
-
-Modern.js 插件是一个对象，对象包含以下属性：
-
-- `name`: 插件的名称，唯一标识符。
-- `setup`: 插件初始化函数，只会执行一次。setup 函数可以返回一个 Hooks 对象，Modern.js 会在特定的时机执行这些 Hooks。
-
-```ts
-const myPlugin = {
-  name: 'my-plugin',
-
-  setup() {
-    // 执行一些初始化逻辑
-    const foo = '1';
-
-    // 返回一个 Hooks 对象
-    return {
-      afterBuild: () => {
-        // 在构建完成后执行逻辑
-      },
-    };
-  },
-};
-```
-
-另外，在插件中，允许配置与其他插件的执行顺序。详情可以参考[插件关系](/guides/topic-detail/framework-plugin/relationship)。
-
-### 插件类型
-
-Modern-js 支持多种工程开发，如应用工程(app-tools), 模块工程(module-tools)等。
-
-为了兼顾不同工程开发的差异和通性，Modern-js 将插件如下图进行组织:
-
-![plugin-relationship](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/modern-website/plugin-relationship.jpg)
-
-从图可以看出，Modern-js 将插件大致分为两类:
-
-1. 通用插件: 插件只会包含一些基础的 Hooks
-
-2. 工程插件: 不同的工程开发会在通用插件的基础上扩展出自己的 Hooks, Config 等类型。
-
-使用 TypeScript 时，可以引入内置的 `CliPlugin` 等类型，为插件提供正确的类型推导。
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-const myPlugin: CliPlugin = {
-  name: 'my-plugin',
-
-  setup() {
-    const foo = '1';
-
-    return {
-      afterBuild: () => {
-        // 在构建完成后执行逻辑
-      },
-    };
-  },
-};
-```
-
-上述代码为通用插件，只包含一些基础的 Hooks。 Modern.js 支持通过泛型对插件的定义进行扩展：
-
-```ts
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-
-const myPlugin: CliPlugin<AppTools> = {
-  name: 'my-plugin',
-
-  setup() {
-    const foo = '1';
-
-    return {
-      afterBuild: () => {
-        // 在构建完成后执行逻辑
-      },
-    };
-  },
-};
-```
-
-如果仔细观察 `AppTools` 这个类型，可以发现 `AppTools` 由 3 种类型构成.
-
-```ts
-type AppTools = {
-  hooks: AppToolsHooks;
-  userConfig: AppToolsUserConfig;
-  normalizedConfig: AppToolsNormalizedConfig;
-};
-```
-
-当编写插件时，插件通过泛型扩展在不同的基础上扩展自己的 Hooks 等类型:
-
-```ts
-// 通用插件上扩展
-import type { CliPlugin } from '@modern-js/core';
-import type { MyPluginHook } from 'xxx';
-
-const myPlugin: CliPlugin<{ hooks: MyPluginHook }> = {};
-```
-
-```ts
-// 在 @modern-js/app-tools 基础上扩展
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-import type { MyPluginHook } from 'xxx';
-
-const myPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
-```
-
-详细说明，请参考 [扩展 Hook](/guides/topic-detail/framework-plugin/extend)。
-
-### 插件配置项
-
-**建议将插件写成函数的形式**，使插件能通过函数入参来接收配置项：
-
-```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](/guides/topic-detail/framework-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 (框架插件)](/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 中的模块工程方案来管理和构建。
-
-首先创建一个空的模块工程方案项目，调整 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/introduction.mdx

@@ -1,51 +0,0 @@
----
-title: 介绍
-sidebar_position: 1
----
-# 介绍
-
-## Modern.js 插件系统
-
-Modern.js 用于扩展项目运行、请求、渲染等不同阶段功能的系统，主要分为三个部分：Hook 模型、管理器，上下文共享机制。
-
-Hook 模型用于确定当前 Hook 的执行方式，不同 Hook 模型的函数拥有不同的执行逻辑。管理器用于控制 Hook 的执行与调度。上下文共享机制用于在不同 Hook 间传递信息。
-
-目前 Modern.js 提供几种不同的 Hook 模型：
-
-- Pipeline
-  - Sync
-  - Async
-- Waterfall
-  - Sync
-  - Async
-- Workflow
-  - Sync
-  - Async
-  - Parallel(Async)
-
-:::note
-后续章节详细介绍各个模型的执行方式。
-
-:::
-
-基于 Hook 模型和管理器，Modern.js 暴露了三套插件：CLI、Runtime、Server。
-
-其中 CLI 插件是 Modern.js 中主要的运行流程控制模型，Modern.js 中绝大部分功能都是主要通过这一套模型运行的。Runtime 插件主要负责处理 React 组件渲染逻辑。Server 插件主要用于对服务端的生命周期以及用户请求的控制。
-
-## 插件可以做什么
-
-Modern.js 的所有功能都是通过这套插件实现的，这意味着 Modern.js 中的所有能力是都对开发者开放的。开发者可以通过编写插件来扩展更多功能，适配复杂场景，包括但不限于：
-
-- 注册命令
-- 修改 Modern.js 配置、配置校验 Schema
-- 修改编译时的 Webpack/Babel/Less/Sass/Tailwind CSS/... 配置
-- 修改运行时需要渲染的 React 组件、Element
-- 修改页面路由
-- 修改服务器路由
-- 自定义控制台输出
-- 自定义动态 HTML 模版
-- 自定义 Node.js 服务器框架
-- 自定义 React 组件客户端/服务器端渲染
-- ...
-
-当 Modern.js 暂时没有覆盖到你所需要的功能或场景时，可以开发一个自定义插件，来实现适配特殊场景的相关功能。

package/zh/guides/topic-detail/framework-plugin/plugin-api.mdx

@@ -1,117 +0,0 @@
----
-title: 插件 API
-sidebar_position: 6
----
-# 插件 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
-
-### useConfigContext
-
-用于获取应用原始配置。
-
-```ts
-const useConfigContext: () => UserConfig;
-
-interface UserConfig {
-  source?: SourceConfig;
-  output?: OutputConfig;
-  server?: ServerConfig;
-  dev?: DevConfig;
-  deploy?: DeployConfig;
-  tools?: ToolsConfig;
-  plugins?: PluginConfig;
-  runtime?: RuntimeConfig;
-  runtimeByEntries?: RuntimeByEntriesConfig;
-}
-```
-
-具体配置字段的意义请参考【[配置](/configure/app/source/alias)】。
-
-### useAppContext
-
-用于获取应用运行上下文。
-
-```ts
-const useAppContext: () => IAppContext;
-
-interface IAppContext {
-  appDirectory: string;
-  configFile: string | false;
-  ip?: string;
-  port?: number;
-  distDirectory: string;
-  packageName: string;
-  srcDirectory: string;
-  sharedDirectory: string;
-  nodeModulesDirectory: string;
-  internalDirectory: string;
-  plugins: {
-    cli?: any;
-    server?: any;
-  }[];
-  entrypoints: Entrypoint[];
-  serverRoutes: ServerRoute[];
-  htmlTemplates: HtmlTemplates;
-}
-```
-
-### useResolvedConfigContext
-
-用于获取解析之后的最终配置。
-
-```ts
-const useResolvedConfigContext: () => NormalizedConfig;
-
-interface NormalizedConfig {
-  source: NormalizedSourceConfig;
-  output: OutputConfig;
-  server: ServerConfig;
-  dev: DevConfig;
-  deploy: DeployConfig;
-  tools: NormalizedToolsConfig;
-  plugins: PluginConfig;
-  runtime: RuntimeConfig;
-  runtimeByEntries?: RuntimeByEntriesConfig;
-  _raw: UserConfig;
-}
-```
-
-具体配置字段的意义请参考【[配置](/configure/app/source/alias)】。
-
-### useHookRunners
-
-用于获取 Hooks 的执行器，并触发特定的 Hook 执行。
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-
-  async setup(api) {
-    const hookRunners = api.useHookRunners();
-    // 触发 afterBuild Hook
-    await hookRunners.afterBuild();
-  },
-});
-```

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

@@ -1,119 +0,0 @@
----
-title: 插件之间的关系
-sidebar_position: 4
----
-# 插件之间的关系
-
-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/develop.mdx

@@ -1,125 +0,0 @@
----
-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/micro-frontend/c01-introduction.mdx

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