@modern-js/main-doc 2.1.0 → 2.2.0

package/zh/configure/app/bff/proxy.mdx

@@ -0,0 +1,74 @@
+---
+sidebar_label: proxy
+---
+
+# bff.proxy
+
+- 类型：`Record<string, string>`
+- 默认值：`{}`
+
+:::info 补充信息
+请先在当前应用项目根目录使用【[new](/apis/app/commands/new)】 启用 BFF 功能。
+
+:::
+
+通过简单配置，无需编写代码，Modern.js 会自动转发请求。发送给 Modern.js BFF server 的请求，会代理到指定的服务上。
+BFF Proxy 使用了强大的 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)，如果需要更多高级的用法， 可以查看它的[文档](https://github.com/chimurai/http-proxy-middleware#options)。
+
+在 `modern.server-runtime.config.js` 中加入以下配置；即可开启代理：
+
+```js title="modern.server-runtime.config.js"
+import { defineConfig } from '@modern-js/app-tools/server';
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api': 'https://cnodejs.org',
+    },
+  },
+});
+```
+
+假设启动的 Modern.js BFF server 的服务地址是 `localhost:8080`，所有 path 以 `api` 开头的请求都会被拦截，如发送到 `localhost:8080/api/v1/topics` 的请求会被代理到 `https://cnodejs.org/api/v1/topics`。
+
+你可以做路径的重写，如将发送到 `localhost:8080/api/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
+
+```ts title="modern.server-runtime.config.ts"
+import { defineConfig } from '@modern-js/app-tools/server';
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api': {
+        target: 'https://cnodejs.org',
+        pathRewrite: { '/api/topics': '/api/v1/topics' },
+        changeOrigin: true,
+      },
+    },
+  },
+});
+```
+
+与 [dev.proxy](/configure/app/dev/proxy) 不同，本节所介绍的代理只作用于进入 BFF/API 服务的请求；同时，这一配置不但可以在开发环境中使用，在生产环境中也会代理相应的请求。
+
+## 常见用法
+
+### 解决接口跨域问题
+
+在项目开发过程中，因为 web 页面和接口服务不是部署在同一个域名下，常常会遇到跨域问题。
+解决跨域问题的方式有很多，在这里我们使用 `bff.proxy` 可以轻松解决跨域问题。
+
+:::info 注
+BFF proxy 模式下，如果不需要写 BFF 的接口， API 目录可以删除；此时 BFF proxy 仍会开启。
+
+:::
+
+如下所示，在 `modern.server-runtime.config.ts` 中，写入如下配置；我们将所有 web 页面发送到同域的以 `/api` 开头的请求代理到另一个域名的服务上。
+
+```ts title="modern.server-runtime.config.ts"
+export default defineServerConfig({
+  bff: {
+    proxy: {
+      '/api': 'https://cnodejs.org',
+    },
+  },
+};
+```

package/zh/configure/app/builder-plugins.mdx

@@ -0,0 +1,73 @@
+---
+title: builderPlugins (构建插件)
+sidebar_position: 10
+---
+# builderPlugins (构建插件)
+
+- 类型：`BuilderPlugin[]`
+- 默认值：`[]`
+
+用于配置 Modern.js Builder 构建插件。
+
+Modern.js Builder 是 Modern.js 底层的构建引擎，请阅读 [构建能力](/guides/basic-features/builder) 了解相关背景。
+
+如果你想了解 Builder 插件的编写方式，可以参考 [Modern.js Builder - 插件系统](https://modernjs.dev/builder/plugins/introduction.html)。
+
+## 注意事项
+
+该选项**用于配置 Modern.js Builder 构建插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+
+- 配置 Modern.js 框架插件，请使用 [plugins](docs/configure/app/plugins) 配置项。
+- 配置 webpack 插件，请使用 [tools.webpack](/configure/app/tools/webpack) 或 [tools.webpackChain](/configure/app/tools/webpack-chain) 配置项。
+- 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
+
+## 何时使用
+
+大部分场景下，我们推荐你使用 Modern.js 框架插件，框架插件可以通过 [plugins](docs/configure/app/plugins) 字段进行注册。因为框架插件提供的 API 更丰富、能力更强，而 Builder 插件提供的 API 只能用于构建场景。
+
+当你需要引用一些现有的 Builder 插件（并且在 Modern.js 中没有相关能力），或是在不同的框架之间复用 Builder 插件时，你可以使用 `builderPlugins` 字段进行注册。
+
+## 示例
+
+下面是 Builder 插件的使用示例。
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```ts title="modern.config.ts"
+import myBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [myBuilderPlugin()],
+});
+```
+
+### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
+
+```ts title="modern.config.ts"
+import myBuilderPlugin from './plugin/myBuilderPlugin';
+
+export default defineConfig({
+  builderPlugins: [myBuilderPlugin()],
+});
+```
+
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
+
+```ts title="modern.config.ts"
+import myBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    myBuilderPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/zh/configure/app/deploy/microFrontend.mdx

@@ -0,0 +1,55 @@
+---
+sidebar_label: microFrontend
+---
+
+# deploy.microFrontend
+
+- 类型：`object`
+- 默认值：`{ enableHtmlEntry: true, externalBasicLibrary: false }`
+
+```ts
+interface MicroFrontend {
+  enableHtmlEntry?: boolean;
+  externalBasicLibrary?: boolean;
+  moduleApp?: string;
+}
+```
+
+开发者可使用 `deploy.microFrontend` 属性来配置微前端子应用的信息。
+
+:::caution 注意
+需要先通过 `pnpm run new` 启用「微前端」 功能。
+
+:::
+
+## 示例
+
+```ts
+export default defineConfig({
+  deploy: {
+    microFrontend: {
+      enableHtmlEntry: true,
+    },
+  },
+});
+```
+
+## 配置项
+
+### enableHtmlEntry
+
+- 类型：`boolean`
+
+- 默认值：`true`
+
+是否启用 html 入口的功能，默认为 `true`，将子应用构建成 `HTML` 模式，Garfish 支持了 `html` 入口，可以开启开选项，体验对应功能，为 HTML 入口时直接将子应用 entry 指向子应用的 html 即可。
+
+可以通过设置为 `false`, 表明子应用构建为 `js`，构建为 `js` 后子应用无法独立运行，为 `JS` 入口时将子应用的入口文件指向子应用的 `JS`
+
+### externalBasicLibrary
+
+- 类型：`boolean`
+
+- 默认值：`false`
+
+是否 `external` 基础库，当设置为 `true` 时，当前子应用将会 `external`：`react`、`react-dom`，`EdenX` 主应用会自动 `setExternal` 这两个基础库，如果其他类型的框架请通过 `Garfish.setExternal` 增加 `react`、`react-dom` 依赖

package/zh/configure/app/dev/proxy.mdx

@@ -0,0 +1,9 @@
+---
+sidebar_label: proxy
+---
+
+# dev.proxy
+
+import GlobalProxyConfig from "@site-docs/components/global-proxy-config"
+
+<GlobalProxyConfig />

package/zh/configure/app/output/disable-node-polyfill.mdx

@@ -0,0 +1,22 @@
+---
+sidebar_label: disableNodePolyfill
+---
+
+# output.disableNodePolyfill
+
+- 类型： `boolean`
+- 默认值： `true`
+
+该配置项用于控制是否在代码中注入 Node 模块的 Polyfill。
+
+默认情况下，我们不会将 Node Polyfill 注入到代码中，以避免造成代码体积增大。如果你需要注入 Node Polyfill，可以将 `output.disableNodePolyfill` 设置为 `false`：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    disableNodePolyfill: false,
+  },
+});
+```
+
+该配置项基于 Modern.js Builder 的 Node Polyfill 插件实现，你可以阅读 [Modern.js Builder - Node Polyfill 插件](https://modernjs.dev/builder/plugins/plugin-node-polyfill.html) 文档来了解详细信息。

package/zh/configure/app/output/ssg.mdx

@@ -0,0 +1,196 @@
+---
+sidebar_label: ssg
+---
+
+# output.ssg
+
+- 类型： `boolean` | `object` | `function`
+- 默认值： `undefined`
+
+开启**自控式路由**或**约定式路由** SSG 功能的配置。
+
+:::info 客户端路由
+相关内容可以查看[路由](/guides/basic-features/routes)。
+
+:::
+
+## 示例
+
+### 单入口
+
+当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。
+
+对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
+
+例如 `src/` 目录下有以下满足**约定式路由**的文件结构：
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+在 `modern.config.js` 中做以下设置：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+});
+```
+
+执行 `pnpm build` 构建应用后。`dist/` 目录将会生成三张 HTML 分别对应三条路由（不开启 SSG 时只有一张 HTML），并且所有 HTML 都已经渲染。
+
+而例如下面的**自控式路由**：
+
+import SelfRouteExample from "@site-docs/components/self-route-example";
+
+<SelfRouteExample />
+
+同样使用上面的配置，在执行 `pnpm run build` 后，只有入口路由 `/` 会生成渲染后的 HTML。
+
+### 多入口
+
+`output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
+
+例如以下目录结构：
+
+```bash
+。
+├── src
+│   ├── entryA
+│   │   └── routes
+│   │       ├── layout.tsx
+│   │       ├── page.tsx
+│   │       └── user
+│   │           ├── layout.tsx
+│   │           ├── page.tsx
+│   │           └── profile
+│   │               └── page.tsx
+│   └── entryB
+│       └── App.tsx
+```
+
+默认情况下，所有约定式路由的入口，在设置 `output.ssg` 配置为 `true` 后都会在构建阶段渲染。可以配置 `false` 来取消指定入口的的默认行为，例如取消上述 entryA 入口在构建时的渲染：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      entryA: true,
+      entryB: false,
+    },
+  },
+});
+```
+
+### 配置路由
+
+上述内容中提到，**自控式路由**默认只会开启入口路由的 SSG 配置。
+
+可以在 `output.ssg` 中设置具体的路由，告知 Modern.js 开启这些客户端路由的 SSG 功能。例如上述 `src/App.tsx` 的文件内容为：
+
+
+<SelfRouteExample />
+
+在 `modern.config.js` 中这样设置后，`/about` 路由也会开启 SSG 功能：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about'],
+    },
+  },
+});
+```
+
+Modern.js 将会自动根据入口拼接完整的 URL 并交给 SSG 插件完成渲染。
+
+也可以为具体入口或路由配置请求头，例如：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      headers: {},
+      routes: [
+        '/',
+        {
+          url: '/about',
+          headers: {},
+        },
+      ],
+    },
+  },
+});
+```
+
+:::info
+路由中设置的 `headers` 会覆盖入口中设置的 `headers`。
+
+:::
+
+### 阻止默认行为
+
+默认情况下，**约定式路由**的路由会全部开启 SSG。Modern.js 提供了另一个字段，用来阻止默认的 SSG 行为。
+
+例如以下目录结构，`/`、`/user`、`/user/profle` 三条路由都开启 SSG：
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+可以这样设置，禁用某一条客户端路由的默认行为：
+
+```js
+export default defineConfig({
+  output: {
+    preventDefault: ['/user'],
+  },
+});
+```
+
+### 添加动态路由参数
+
+部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id]/page.tsx` 文件生成的路由。
+
+可以在 `output.ssg` 中配置具体的参数，渲染指定参数的路由，例如：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: [
+        {
+          url: '/user/:id',
+          params: [
+            {
+              id: 'modernjs',
+            },
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+动态路由和 SSG 的组合，在根据 CMS 系统数据变更，实时生成静态页面时非常有用。

package/zh/configure/app/plugins.mdx

@@ -0,0 +1,81 @@
+---
+title: plugins (插件)
+sidebar_position: 9
+---
+# plugins (插件)
+
+- 类型：`CliPlugin[]`
+- 默认值：`[]`
+
+用于配置自定义的 Modern.js 框架插件。
+
+自定义插件的编写方式请参考 [如何编写插件](/guides/topic-detail/framework-plugin/implement)。
+
+## 注意事项
+
+该选项**用于配置框架插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+
+- 配置 Modern.js Builder 插件，请使用 [builderPlugins](docs/configure/app/builder-plugins) 配置项。
+- 配置 webpack 插件，请使用 [tools.webpack](/configure/app/tools/webpack) 或 [tools.webpackChain](/configure/app/tools/webpack-chain) 配置项。
+- 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
+
+## 插件类型
+
+Modern.js 中内置了三种不同的框架插件：
+
+- `CLI 插件`，适用于本地开发、编译构建阶段，可以在命令行和编译阶段扩展各种能力。
+- `Server 插件`，适用于服务端。
+- `Runtime 插件`，适用于前端运行时。
+
+目前 Modern.js 开放了自定义 CLI 插件的能力，Server 插件和 Runtime 插件会在后续开放。
+
+## 插件执行顺序
+
+默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
+
+当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](/guides/topic-detail/framework-plugin/relationship)。
+
+## 示例
+
+下面是 CLI 插件的使用示例。
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```ts title="modern.config.ts"
+import myPlugin from 'my-plugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
+
+```ts title="modern.config.ts"
+import myPlugin from './config/plugin/myPlugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
+
+```ts title="modern.config.ts"
+import myPlugin from 'my-plugin';
+
+export default defineConfig({
+  plugins: [
+    myPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```