@modern-js/main-doc 2.1.0 → 2.3.0

package/zh/components/prerequisites.mdx

@@ -0,0 +1,20 @@
+### Node.js
+
+需要 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 v16.18.1。
+
+Modern.js 推荐在开发环境里先安装 [nvm](https://github.com/nvm-sh/nvm#install--update-script)，在 shell 里集成[自动切换 node 版本的脚本](https://github.com/nvm-sh/nvm#deeper-shell-integration)。
+
+然后只要仓库根目录下有内容为 `lts/gallium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
+
+### pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
+
+```bash
+npm install -g pnpm
+```
+
+:::note
+Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
+
+:::

package/zh/components/reduck-tip.mdx

@@ -0,0 +1,8 @@
+
+
+:::info 补充信息
+默认情况下，本节所有 API 的导出包名为：`@modern-js/runtime/model`。
+
+如果是在 Modern.js 以外单独集成 Reduck，导出包名为：`@modern-js-reduck/react`。
+
+:::

package/zh/components/self-route-example.mdx

@@ -0,0 +1,21 @@
+```tsx title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+import React from 'react';
+import { useRuntimeContext } from '@modern-js/runtime';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  const pathname = context?.request?.pathname;
+  return (
+    <Router location={pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```

package/zh/configure/app/auto-load-plugin.mdx

@@ -0,0 +1,62 @@
+---
+title: autoLoadPlugins (自动注册插件)
+sidebar_position: 11
+---
+# autoLoadPlugins (自动注册插件)
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+用于配置 Modern.js 是否开启自动注册插件。
+
+### 手动注册插件
+
+默认情况下，安装插件后，你需要在 `modern.config.ts` 文件中手动注册插件。
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import i18nPlugin from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [appTools(), i18nPlugin()],
+});
+```
+
+### 自动注册插件
+
+除了手段注册，Modern.js 还提供自动注册插件的方式: 将 `autoLoadPlugin` 配置项置为 `true`。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  autoLoadPlugins: true,
+});
+```
+
+Modern.js 将通过以下几个步骤帮你自动注册插件
+
+1. Modern.js 在内部维护一份官方插件列表。
+
+```js
+const InternalPlugins = ['@modern-js/app-tools', '@modern-js/plugin-i18n', ...];
+```
+
+2. Modern.js 将读取你的 `package.json` 文件，收集依赖信息。
+
+```json title="package.json"
+"dependencies": {
+  "@modern-js/plugin-i18n": "x.x.x"
+  ...
+},
+"devDependencies": {
+  "@modern-js/app-tools": "x.x.x"
+  ...
+}
+```
+
+3. Modern.js 观察到你安装了 `@modern-js/plugin-i18n` 和 `@modern-js/app-tools` 等依赖后，将会引入插件自动注册。
+
+可以注意到这种方式相对黑盒，你甚至对加载插件的过程是无感知的。我们希望更多的细节暴露给开发者，能让开发者去控制这一过程。
+
+**因此我们更加推荐你手动注册插件。**

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

@@ -0,0 +1,34 @@
+---
+sidebar_label: prefix
+---
+
+# bff.prefix
+
+- **类型：** `string`
+- **默认值：** `/api`
+
+:::caution 注意
+请先在当前应用项目根目录使用【[new](/apis/app/commands/new)】 启用 BFF 功能。
+
+:::
+
+默认情况下，BFF API 目录下的路由访问前缀是 `/api`, 如下目录结构：
+
+```bash
+api
+└── hello.ts
+```
+
+`api/hello.ts` 访问时对应的路由为 `localhost:8080/api/hello`。
+
+该配置选项可以修改默认的路由前缀：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo',
+  },
+});
+```
+
+对应的 `api/hello.ts` 访问路由为 `localhost:8080/api-demo/hello`。

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/asset-prefix.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: assetPrefix
+---
+
+# dev.assetPrefix
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.assetPrefix](https://modernjs.dev/builder/api/config-dev.html#dev-assetprefix)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/assetPrefix.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: hmr
+---
+
+# dev.hmr
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.hmr](https://modernjs.dev/builder/api/config-dev.html#dev-hmr)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/hmr.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: https
+---
+
+# dev.https
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.https](https://modernjs.dev/builder/api/config-dev.html#dev-https)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/https.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: port
+---
+
+# dev.port
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.port](https://modernjs.dev/builder/api/config-dev.html#dev-port)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/port.md'
+
+<Main />

package/zh/configure/app/dev/progress-bar.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: progressBar
+---
+
+# dev.progressBar
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.progressBar](https://modernjs.dev/builder/api/config-dev.html#dev-progressbar)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/progressBar.md'
+
+<Main />

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/dev/start-url.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: startUrl
+---
+
+# dev.startUrl
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.startUrl](https://modernjs.dev/builder/api/config-dev.html#dev-starturl)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/startUrl.md'
+
+<Main />

package/zh/configure/app/experiments/lazy-compilation.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: lazyCompilation
+---
+
+# experiments.lazyCompilation
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [experiments.lazyCompilation](https://modernjs.dev/builder/api/config-experiments.html#experiments-lazycompilation)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/experiments/lazyCompilation.md'
+
+<Main />

package/zh/configure/app/html/app-icon.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: appIcon
+---
+
+# html.appIcon
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.appIcon](https://modernjs.dev/builder/api/config-html.html#html-appicon)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/appIcon.md'
+
+<Main />

package/zh/configure/app/html/crossorigin.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: crossorigin
+---
+
+# html.crossorigin
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.crossorigin](https://modernjs.dev/builder/api/config-html.html#html-crossorigin)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/crossorigin.md'
+
+<Main />

package/zh/configure/app/html/disable-html-folder.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: disableHtmlFolder
+---
+
+# html.disableHtmlFolder
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.disableHtmlFolder](https://modernjs.dev/builder/api/config-html.html#html-disablehtmlfolder)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/disableHtmlFolder.md'
+
+<Main />

package/zh/configure/app/html/favicon-by-entries.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: faviconByEntries
+---
+
+# html.faviconByEntries
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.faviconByEntries](https://modernjs.dev/builder/api/config-html.html#html-faviconbyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/faviconByEntries.md'
+
+<Main />

package/zh/configure/app/html/favicon.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: favicon
+---
+
+# html.favicon
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.favicon](https://modernjs.dev/builder/api/config-html.html#html-favicon)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/favicon.md'
+
+<Main />

package/zh/configure/app/html/inject-by-entries.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: injectByEntries
+---
+
+# html.injectByEntries
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.injectByEntries](https://modernjs.dev/builder/api/config-html.html#html-injectbyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/injectByEntries.md'
+
+<Main />

package/zh/configure/app/html/inject.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: inject
+---
+
+# html.inject
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.inject](https://modernjs.dev/builder/api/config-html.html#html-inject)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/inject.md'
+
+<Main />

package/zh/configure/app/html/meta-by-entries.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: metaByEntries
+---
+
+# html.metaByEntries
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.metaByEntries](https://modernjs.dev/builder/api/config-html.html#html-metabyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/metaByEntries.md'
+
+<Main />

package/zh/configure/app/html/meta.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: meta
+---
+
+# html.meta
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.meta](https://modernjs.dev/builder/api/config-html.html#html-meta)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/meta.md'
+
+<Main />

package/zh/configure/app/html/mount-id.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: mountId
+---
+
+# html.mountId
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.mountId](https://modernjs.dev/builder/api/config-html.html#html-mountid)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/mountId.md'
+
+<Main />

package/zh/configure/app/html/tags-by-entries.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: tagsByEntries
+---
+
+# html.tagsByEntries
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.tagsByEntries](https://modernjs.dev/builder/api/config-html.html#html-tagsbyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/tagsByEntries.md'
+
+<Main />

package/zh/configure/app/html/tags.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: tags
+---
+
+# html.tags
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.tags](https://modernjs.dev/builder/api/config-html.html#html-tags)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/tags.md'
+
+<Main />

package/zh/configure/app/html/template-by-entries.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: templateByEntries
+---
+
+# html.templateByEntries
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.templateByEntries](https://modernjs.dev/builder/api/config-html.html#html-templatebyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/templateByEntries.md'
+
+<Main />