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

package/zh/components/command-tip.md

@@ -0,0 +1,57 @@
+:::tip 提示
+pnpm v6 和 pnpm v7 版本在执行命令时使用姿势不完全一致，需要注意以下事项：
+
+pnpm v7：
+
+在使用 pnpm 调用 `package.json` 中的命令时，如果需要传递参数至 pnpm，需要将参数放到命令前。
+
+例如使用 pnpm `--filter` 参数执行 prepare 命令：
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+如果需要传递参数至命令，需要将参数放到命令后。
+
+例如，在如下 `package.json` 配置中：
+
+``` json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+执行 command 命令时携带参数方式为：
+```bash
+pnpm run command --options
+```
+
+pnpm v6:
+
+在如下 `package.json` 配置中：
+
+``` json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+当需要执行 `modern command --option`：
+
+使用 pnpm 时，需要执行 `pnpm run command -- --option`。
+
+这是因为 pnpm 对于命令参数的处理与 Yarn 并不相同，但是与 npm 类似：在不加 `--` 字符串的时候，传递的是 pnpm 的参数；在使用 `--` 字符串的时候，传递的是执行脚本的参数。
+
+在上述例子里参数 `--option` 传递给了 `modern command`。如果执行 `pnpm run command --option`，则参数 `--option` 将传递给 pnpm。
+
+总结来说：
+
+**在使用 pnpm v7 时，如果传递参数给 pnpm，需要将参数放置到命令前**
+
+**在使用 pnpm v6 时，如果传递的参数给 pnpm，不需要加 `--`；如果传递的参数是给脚本使用，需要增加 `--` 字符串**。
+
+:::

package/zh/components/deploy.md

@@ -0,0 +1,60 @@
+Modern.js 支持通过云平台一键部署应用。
+
+使用云平台部署应用，我们需要先开启部署功能。在项目根目录下执行 `pnpm run new`，进行如下选择：
+
+```bash
+? 请选择你想要的操作：启用可选功能
+? 启用可选功能：启用「部署」功能
+? 默认使用框架自带的专业 Web 服务器，是否调整：否
+? 请选择 CDN 平台：阿里云 OSS
+? 请选择云函数平台：阿里云 FC
+```
+
+安装依赖后，可以看到 package.json 中新增了两项依赖：
+
+```bash
++ "@modern-js/plugin-lambda-fc": "^1"
++ "@modern-js/plugin-cdn-fc": "^1"
+```
+
+我们可以在项目根目录下的 `.env` 中添加云平台必要的账号信息，以阿里云为例，包括 `accountId`、`secretId` 和 `secretKey`。使用 CDN 上传还需要配置 `bucketName`。
+
+部分**可暴露的、可以进入代码仓库**的环境变量可以放在项目的 `.env` 文件中，例如：
+
+```bash
+# 阿里云账号 ID
+CLOUD_ACCOUNT_ID
+# 阿里云 OSS Bucket 名称
+CLOUD_BUCKET_NAME
+```
+
+鉴权相关信息**必须在平台上配置，不能进入代码仓库**。为了方便本地测试，我们临时的在 `.env` 中添加：
+
+```bash
+# 阿里云访问 AK
+CLOUD_SECRET_ID
+# 阿里云访问 SK
+CLOUD_SECRET_KEY
+```
+
+:::warning 警告
+此处仅仅是用于本地测试，SecretID/SecretKey 必须从代码中移除，避免信息泄露。
+:::
+
+1. AccountID 在[阿里云账号中心页](https://account.console.aliyun.com/v2/#/basic-info/index)获取。
+
+2. SecretID（AccessKey ID），SecretKey（AccessKey Secret），在[用户信息管理页](https://usercenter.console.aliyun.com/#/manage/ak)获取。
+
+3. Bucket 信息可以从阿里云 OSS 的 [Bucket 列表](https://oss.console.aliyun.com/bucket)中获取。
+
+我们可以根据 OSS 的 Bucket 名称和 Region 名称拼接出 OSS 的临时域名，并设置为[静态资源域名前缀](/docs/configure/app/output/asset-prefix)：
+
+```js
+export default defineConfig({
+  output: {
+    assetPrefix: "https://{bucketName}.oss-{bucketRegion}.aliyuncs.com/"
+  }
+}
+```
+
+执行 `pnpm run deploy` 命令后，应用将会先执行构建，将静态资源上传到 OSS 以及将应用部署到阿里云 FC 中。

package/zh/components/dev-ide.md

@@ -0,0 +1 @@
+Modern.js 对 VS Code 等主流 IDE 提供了开箱即用的支持，具备 Lint 问题自动检测、自动修复，代码提交前的准入检查等功能特性，可以让代码开发更加高效和智能。详细介绍请参考【[确认编程环境](/docs/tutorials/first-app/c03-ide/3.1-setting-up)】。

package/zh/components/entry-name.md

@@ -0,0 +1,15 @@
+## 入口名称
+
+默认情况下，「入口名称」为页面入口所在目录的名称。
+
+例如，项目的目录结构如下时，入口名称为 `page-a` 和 `page-b`。
+
+```
+└── src
+    ├── page-a
+    │   └── App.jsx
+    └── page-b
+        └── App.jsx
+```
+
+如果使用 [source.entries](/docs/configure/app/source/entries) 自定义了页面入口，则「入口名称」为 `source.entries` 对象的 `key`。

package/zh/components/env-prepare.md

@@ -0,0 +1 @@
+开始之前，请参考【[环境准备](/docs/tutorials/first-app/c01-getting-started/1.1-prerequisites)】部分，确保本地环境正常。

package/zh/components/launch-bff-choices.md

@@ -0,0 +1,6 @@
+```bash
+? 请选择你想要的操作: 启用可选功能
+? 启用可选功能: 启用「BFF」功能
+? 请选择 BFF 类型：函数写法
+？请选择运行时框架：Express
+```

package/zh/components/reduck-tip.md

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

package/zh/configure/app/bff/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "bff (BFF API)",
+  "position": 5
+}

package/zh/configure/app/bff/fetcher.md

@@ -0,0 +1,32 @@
+---
+sidebar_label: fetcher
+sidebar_position: 2
+---
+
+# bff.fetcher
+
+
+
+* 类型：`string`
+* 默认值：
+  * 浏览器端：[global.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+  * Node.js 端：[node-fetch](https://github.com/node-fetch/node-fetch)
+
+:::caution 注意
+应用工程需要请确保使用【[new](/docs/apis/app/commands/new)】 启用了 BFF 功能。
+:::
+
+
+自定义 `fetch` 函数，可以用于 Native、小程序场景下的 `fetch` 函数定制。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    fetcher: 'custom-fetch'
+  }
+});
+```
+
+:::info 注
+这里定制就需要定制两种场景下的 `fetch` 函数，即自行判断运行环境，实现同构的 fetch 函数。
+:::

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

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

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

@@ -0,0 +1,76 @@
+---
+sidebar_label: proxy
+sidebar_position: 1
+---
+
+# bff.proxy
+
+
+
+* 类型：`Record<string, string>`
+* 默认值：`{}`
+
+:::info 补充信息
+应用工程需要请确保使用【[new](/docs/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`。
+
+```js title="modern.server-runtime.config.js"
+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](/docs/configure/app/dev/proxy) 不同，本节所介绍的代理只作用于进入 BFF/API 服务的请求。
+
+同时，这一配置不但可以在开发环境中使用，在生产环境也会生成真实代码并且与项目一同部署。
+
+## 常见用法
+
+### 解决接口跨域问题
+
+在项目开发过程中，因为 web 页面和接口服务不是部署在同一个域名下，常常会遇到跨域问题。
+解决跨域问题的方式有很多，在这里我们使用 `bff.proxy` 可以轻松解决跨域问题。
+
+:::info 注
+BFF proxy 模式下，如果不需要写 BFF 的接口， API 目录可以删除；此时 BFF proxy仍会开启。
+:::
+
+如下所示，在 `modern.server-runtime.config.js` 中，写入如下配置；我们将所有 web 页面发送到同域的以 `/api` 开头的请求代理到另一个域名的服务上。
+
+```js title="modern.server-runtime.config.js"
+export default defineServerConfig({
+  bff: {
+    proxy: {
+      '/api': 'https://cnodejs.org',
+    },
+  },
+};
+```

package/zh/configure/app/dev/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "dev (开发调试)",
+  "position": 7
+}

package/zh/configure/app/dev/asset-prefix.md

@@ -0,0 +1,13 @@
+---
+title: dev.assetPrefix
+sidebar_label: assetPrefix
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [dev.assetPrefix](https://modernjs.dev/builder/zh/api/config-dev.html#dev-assetprefix)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/dev/assetPrefix.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: dev.hmr
+sidebar_label: hmr
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [dev.hmr](https://modernjs.dev/builder/zh/api/config-dev.html#dev-hmr)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/dev/hmr.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: dev.https
+sidebar_label: https
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [dev.https](https://modernjs.dev/builder/zh/api/config-dev.html#dev-https)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/dev/https.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: dev.port
+sidebar_label: port
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [dev.port](https://modernjs.dev/builder/zh/api/config-dev.html#dev-port)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/dev/port.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: dev.progressBar
+sidebar_label: progressBar
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [dev.progressBar](https://modernjs.dev/builder/zh/api/config-dev.html#dev-progressbar)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/dev/progressBar.md'
+
+<Main />

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

@@ -0,0 +1,79 @@
+---
+sidebar_label: proxy
+sidebar_position: 1
+---
+
+# dev.proxy
+
+
+
+* 类型： `string | Object`
+* 默认值： `null`
+
+配置该选项后，开发环境时会启动全局代理，类似 [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) 等 web 代理调试工具，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
+
+
+:::tip 提示
+使用该选项需要提前安装 `@modern-js/plugin-proxy`。
+:::
+
+值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
+
+例如：
+
+```js title="modern.config.js"
+export default defineConfig({
+  dev: {
+    proxy: {
+      'https://www.baidu.com': 'https://google.com.hk',
+      //可以通过 file 协议直接返回静态文件。
+      'https://example.com/api': 'file://./data.json',
+    }
+  }
+});
+```
+
+值为 `string` 时， 可以用来指定单独的代理文件，例如：
+
+
+```js title="modern.config.js"
+export default defineConfig({
+  dev: {
+    proxy: './proxy.js',
+  },
+});
+```
+
+```js title="proxy.js"
+module.exports = {
+  name: 'my-app',
+  rules: `
+    ^example.com:8080/api/***   http://localhost:3001/api/$
+  `,
+};
+```
+
+:::info 注
+Modern.js 全局代理实现底层基于 [whistle](https://wproxy.org/whistle/), 更多匹配模式请参考: [匹配模式](https://wproxy.org/whistle/pattern.html)
+:::
+
+执行 `dev`, 提示如下时，即代理服务器启动成功：
+
+```bash
+  App running at:
+
+  Local:    http://localhost:8080/
+  Network:  http://192.168.0.1:8080/
+
+ℹ  info      Starting the proxy server.....
+✔  success   Proxy Server start on localhost:8899
+```
+
+访问 `localhost:8899`, 可以在 UI 界面上查看 Network 以及配置代理规则：
+
+![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
+
+:::caution 注意
+https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
+:::
+

package/zh/configure/app/dev/start-url.md

@@ -0,0 +1,13 @@
+---
+title: dev.startUrl
+sidebar_label: startUrl
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [dev.startUrl](https://modernjs.dev/builder/zh/api/config-dev.html#dev-starturl)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/dev/startUrl.md'
+
+<Main />

package/zh/configure/app/dev/with-master-app.md

@@ -0,0 +1,35 @@
+---
+sidebar_label: withMasterApp
+sidebar_position: 2
+---
+
+# dev.withMasterApp
+
+
+
+* 类型： `Object`
+* 默认值： `null`
+
+当项目为微前端子应用的时候，可以使用 `withMasterApp` 配置启用子应用调试模式。
+
+:::caution 注意
+使用子应用调试的模式时，应该先确保主应用开启了线上 debug 模式。
+:::
+
+```js title=modern.config.js
+export default defineConfig({
+  dev: {
+    withMasterApp: {
+      // 主应用的路径
+      moduleApp: 'https://www.masterApp.com',
+      // 子应用的名称
+      moduleName: 'Contact'
+    }
+  }
+})
+```
+
+- moduleApp: `string` 主应用的线上地址。
+- moduleName: `Contact` 子应用的名称（需要和在主应用中注册的模块名匹配）。
+
+详细使用方式，请参考【[微前端子应用](/docs/guides/topic-detail/micro-frontend/debugging)】。

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

@@ -0,0 +1,13 @@
+---
+title: html.appIcon
+sidebar_label: appIcon
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.appIcon](https://modernjs.dev/builder/zh/api/config-html.html#html-appicon)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/appIcon.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.crossorigin
+sidebar_label: crossorigin
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.crossorigin](https://modernjs.dev/builder/zh/api/config-html.html#html-crossorigin)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/crossorigin.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.disableHtmlFolder
+sidebar_label: disableHtmlFolder
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.disableHtmlFolder](https://modernjs.dev/builder/zh/api/config-html.html#html-disablehtmlfolder)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/disableHtmlFolder.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.faviconByEntries
+sidebar_label: faviconByEntries
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.faviconByEntries](https://modernjs.dev/builder/zh/api/config-html.html#html-faviconbyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/faviconByEntries.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.favicon
+sidebar_label: favicon
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.favicon](https://modernjs.dev/builder/zh/api/config-html.html#html-favicon)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/favicon.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.injectByEntries
+sidebar_label: injectByEntries
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.injectByEntries](https://modernjs.dev/builder/zh/api/config-html.html#html-injectbyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/injectByEntries.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.inject
+sidebar_label: inject
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.inject](https://modernjs.dev/builder/zh/api/config-html.html#html-inject)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/inject.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.metaByEntries
+sidebar_label: metaByEntries
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.metaByEntries](https://modernjs.dev/builder/zh/api/config-html.html#html-metabyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/metaByEntries.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.meta
+sidebar_label: meta
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.meta](https://modernjs.dev/builder/zh/api/config-html.html#html-meta)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/meta.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+title: html.mountId
+sidebar_label: mountId
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [html.mountId](https://modernjs.dev/builder/zh/api/config-html.html#html-mountid)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/html/mountId.md'
+
+<Main />