@modern-js/main-doc 0.0.0-next-20221123182933 → 0.0.0-next-20221124071519

package/zh/apis/app/commands/upgrade.md

@@ -14,8 +14,6 @@ Options:
   -h, --help             display help for command
 ```
 
-`modern upgrade` 命令，用于升级项目 Modern.js 相关依赖至最新版本。
-
 在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
 
 :::info

package/zh/apis/app/hooks/api/framework/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "框架写法",
+  "label": "Framework Mode",
   "position": 2
 }

package/zh/apis/app/hooks/api/framework/lambda.md

@@ -3,11 +3,13 @@ title: lambda/*.[tj]s
 sidebar_position: 1
 ---
 
-声明 API 路由的文件，在 Modern.js 函数写法下；除了[某些约定文件](/docs/apis/app/hooks/api/framework/lambda#白名单)外，`api` 目录下的文件会被注册为接口的路由。
+在 BFF 框架写法下，声明 API 路由的文件。除了[某些约定文件](/docs/apis/app/hooks/api/framework/lambda#白名单)外，`api/` 目录下的文件会被注册为接口的路由。
 
-:::info 注
+:::info
 使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
+:::
 
+:::tip
 该文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
 :::
 
@@ -20,9 +22,9 @@ sidebar_position: 1
 * `api/lambda/index.ts` -> `$BASENAME/`
 * `api/lambda/user/index.ts` -> `$BASENAME/user`
 
-### 嵌套路由
+### 多级路由
 
-路由系统也支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
+路由系统也支持解析多级的文件，如果创建文件夹结构，文件仍会以相同方式自动解析路由。
 
 * `api/lambda/hello.ts` -> `$BASENAME/hello`
 * `api/lambda/user/list.ts` -> `$BASENAME/user/list`
@@ -49,31 +51,4 @@ sidebar_position: 1
 
 ## 函数定义
 
-除了上面的路由规则之外，代码中函数定义与导出也有相应的约定。
-
-* 首先命名导出时，导出函数的名字为对应接口接受的 HTTP Method。
-
-即：
-
-```ts
-export const get = async () => {
-  return {
-    name: 'Modern.js',
-    desc: '现代 web 工程方案',
-  };
-};
-```
-
-这样导出函数，则会得到一个 `POST` 接口。
-
-应用工程中支持了 9 个 Method 定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。
-
-名字是大小不敏感的，就是说，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
-
-因为 `delete` 是 `javascript` 中的关键字，可以使用 `del` 或者 `DELETE` 代替。
-
-可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
-
-:::info 注
-需要注意的是，定义的函数都应该是异步的，这个与函数调用时类型有关，这个后面会提到。
-:::
+和函数写法下[函数定义](/docs/apis/app/hooks/api/functions/api#define-function)完全一致。

package/zh/apis/app/hooks/api/functions/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "函数写法",
+  "label": "Function Mode",
   "position": 1
 }

package/zh/apis/app/hooks/api/functions/api.md

@@ -3,7 +3,7 @@ title: "**/*.[tj]s"
 sidebar_position: 1
 ---
 
-声明 API 路由的文件，在 Modern.js 函数写法下；除了[某些约定文件](/docs/apis/app/hooks/api/functions/api)外，`api` 目录下的文件会被注册为接口的路由。
+在 BFF 函数写法下，声明 API 路由的文件。除了[某些约定文件](/docs/apis/app/hooks/api/functions/api)外，`api` 目录下的文件会被注册为接口的路由。
 
 :::info 注
 使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
@@ -47,4 +47,31 @@ sidebar_position: 1
 * TypeScript 类型文件。例如：`hello.d.ts`。
 * `node_module` 下的文件。
 
+## 函数定义
 
+除了上面的路由规则之外，代码中函数定义与导出也有相应的约定。
+
+函数通过具名导出，导出函数的名字为对应接口接受的 HTTP Method，即：
+
+```ts
+export const get = async () => {
+  return {
+    name: 'Modern.js',
+    desc: '现代 web 工程方案',
+  };
+};
+```
+
+这样导出函数，则会得到一个 `POST` 接口。
+
+应用工程中支持了 9 个 Method 定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。
+
+名字是大小不敏感的，就是说，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
+
+因为 `delete` 是 JavaScript 中的关键字，可以使用 `del` 或者 `DELETE` 代替。
+
+可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
+
+:::info 注
+需要注意的是，定义的函数都应该是异步的，这个与函数调用时类型有关，这个后面会提到。
+:::

package/zh/apis/app/hooks/api/functions/common.md

@@ -3,8 +3,6 @@ title: "**/_*.[tj]s, _*/**"
 sidebar_position: 2
 ---
 
-在 Modern.js 函数写法下，这些文件不会注册为路由；你可以在这种目录或文件下放任意项目中需要的代码，文件等。
+在 BFF 函数写法下，这些文件不会注册为路由。
 
-:::info 注
-使用 `api` 目录的开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
-:::
+你可以在这种目录或文件下放任意项目中需要的代码，文件等。

package/zh/apis/app/hooks/api/test.md

@@ -3,9 +3,7 @@ title: test.[tj]s
 sidebar_position: 2
 ---
 
-应用项目 BFF 测试文件。
-
-应用项目支持在项目 API 目录下创建后缀为 `.test.[tj]sx?` 文件进行编写测试用例。
+应用的 BFF 测试文件，支持在 `api/` 目录后缀为 `.test.[tj]sx?` 的文件中编写测试用例。
 
 :::info 注
 使用单元测试、集成测试需要提前在项目下执行 new 命令启用「单元测试 / 集成测试」功能。

package/zh/apis/app/hooks/config/html.md

@@ -3,8 +3,6 @@ title: html/
 sidebar_position: 1
 ---
 
-应用工程方案自定义 html 片段文件。
-
 通过 `config/html` 目录可以在内部默认 html 模板的不同位置注入自定义的 html 片段。
 
 具体使用方式请参考: [自定义 HTML](/docs/guides/basic-features/html)

package/zh/apis/app/hooks/config/icon.md

@@ -5,7 +5,7 @@ sidebar_position: 2
 
 应用工程方案 App Icon 文件。
 
-项目根目录下 `config/icon.png` 时，可以在构建时在 html 页面注入 app icon 信息, 如下:
+项目根目录下 `config/icon.png` 时，可以在构建时向 html 页面注入 app icon 信息：
 
 ```
 ./config

package/zh/apis/app/hooks/config/mock.md

@@ -3,10 +3,4 @@ title: mock/
 sidebar_position: 5
 ---
 
-应用工程方案本地调试 Mock 数据文件。
-
-项目根目录下存在 `config/mock/index.js` 时，在本地开发调试环节自动启用快速 Mock 数据的功能。
-
-:::caution 注意
-为避免 Mock API 不生效， 请注意不要与配置 [tools.devServer.proxy](/docs/configure/app/tools/dev-server) 的 API 有冲突。
-:::
+项目根目录下存在 `config/mock/index.js` 时，在开发环节自动开启 Mock 服务。

package/zh/apis/app/hooks/config/public.md

@@ -3,13 +3,11 @@ title: public/
 sidebar_position: 3
 ---
 
-应用工程方案静态资源文件。
-
 `public/` 目录中可以放置任意格式的静态资源文件，文件会被 Serve 在 Web 应用域名下。
 
 ## 说明
 
-被 Serve 的文件路由基于目录结构的约定，其中，`public/` 为根目录，对应 Web 应用根域名。
+被 Serve 的文件路由基于目录结构的约定，其中，`public/` 为根目录，对应 Web 应用根路径。
 
 例如 `config/public/sdk/index.js` 文件，在部署后将会被 Serve 在 `${domain}/sdk/index.js` 下。
 

package/zh/apis/app/hooks/config/storybook.md

@@ -3,9 +3,7 @@ title: storybook/
 sidebar_position: 7
 ---
 
-应用工程方案 Storybook 配置文件。
-
-应用工程方案支持使用 Storybook 进行调试，当需要对 Storybook 进行配置时，需要在项目 config/storybook 目录进行配置。
+Modern.js 支持使用 Storybook 进行调试，当需要对 Storybook 进行配置时，需要在项目 config/storybook 目录进行配置。
 
 Storybook 配置请查看：[Storybook 配置](https://storybook.js.org/docs/react/configure/overview)
 

package/zh/apis/app/hooks/config/upload.md

@@ -3,8 +3,6 @@ title: upload/
 sidebar_position: 4
 ---
 
-应用工程方案静态资源文件。
-
 `upload/` 目录中可以放置任意格式的静态资源文件。
 
 ## 说明
@@ -19,8 +17,6 @@ sidebar_position: 4
 
 图片、字体文件、通用 CSS 等。
 
-如果并非必要，Modern.js 推荐将 JS / CSS 这类文件通过 `upload/` 上传到 CDN，而不使用 `public/`。
-
 ## 代码压缩
 
 如果目录下的文件是一个 `.js` 文件，在生产环境构建时，会自动对其进行代码压缩。
@@ -43,6 +39,4 @@ sidebar_position: 4
 
 :::info 注
 Modern.js 没有支持在 `config/public/*.css`（例如 background-image）中通过 URL 使用 `config/upload/` 下的文件。
-
-因为 Modern.js 不推荐在 `public/` 中放 JS、CSS 这类资源文件，可以将它们直接放置在 `upload/` 目录下。
 :::

package/zh/apis/app/hooks/modern-config.md

@@ -3,8 +3,6 @@ title: modern.config.js
 sidebar_position: 8
 ---
 
-应用工程方案的 Modern.js 配置文件。
-
-通过该文件可以对当前项目的各个方面进行个性化配置。
+Modern.js 配置文件, 通过该文件可以对当前项目的各个方面进行个性化配置。
 
 了解配置的具体用法，请参考 [配置使用](/docs/configure/app/usage)。

package/zh/apis/app/hooks/server/index_.md

@@ -3,10 +3,10 @@ title: index.[tj]s
 sidebar_position: 1
 ---
 
-扩展 Modern.js Server 的文件，在此文件中可以给应用工程启动的 Web Server 添加前置中间件。
+扩展 Modern.js Web Server 的文件，在此文件中可以给应用工程启动的 Web Server 添加 Hook 或 Middleware。
 
-可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等；也可在 Server 的运行流程中（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。
+可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等。也可在内置处理逻辑（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。
 
-:::info 注
-具体使用示例可查看 [Hook](/docs/apis/app/runtime/web-server/hook)。
+:::info
+具体使用示例可查看 [Hook](/docs/apis/app/runtime/web-server/hook) & [Middleware](/docs/apis/app/runtime/web-server/middleware)。
 :::

package/zh/apis/app/hooks/server/test.md

@@ -5,7 +5,7 @@ sidebar_position: 2
 
 扩展 Web Server 测试目录。
 
-应用项目支持对扩展 Web Server 逻辑进行测试，可直接在项目 server 目录下创建后缀为 `.test.[tj]s` 文件进行编写测试用例。
+应用支持对扩展 Web Server 逻辑进行测试，可直接在项目 `server/` 目录下创建后缀为 `.test.[tj]s` 文件进行编写测试用例。
 
 :::info 注
 使用单元测试、集成测试需要提前在项目下执行 new 命令启用「单元测试 / 集成测试」功能。

package/zh/apis/app/hooks/shared.md

@@ -3,6 +3,5 @@ title: shared/
 sidebar_position: 5
 ---
 
-应用工程方案共享源码目录。
+共享源码目录。当项目在 `api/`、`server/`、`src/` 下有公共代码时，可将这些代码放到 shared 目录下，而不是直接引用。
 
-在项目中同时用到了 BFF 和扩展 Web Server 功能，并且它们之间存在一些公共服务端代码时，可将这些公共代码放到 shared 目录下。

package/zh/apis/app/hooks/src/app.md

@@ -3,13 +3,14 @@ title: App.[tj]sx
 sidebar_position: 1
 ---
 
-应用项目无路由或者任意路由的入口标识。
+应用使用自控路由时的入口标识符。
 
-开发单页面应用的场景，推荐 `src` 文件夹下放置 `App.[tj]sx` 导出应用根组件即可，Modern.js 会自动生成真正的构建打包的入口文件, 内容大致如下:
+`App.[tj]sx` 并不是实际的应用入口，Modern.js 会自动生成真正的构建打包的入口文件, 内容大致如下：
 
 ```js
 import React from 'react';
 import { createApp, bootstrap } from '@modern-js/runtime';
+// App.[jt]sx
 import App from '@_modern_js_src/App';
 import { state } from '@modern-js/runtime/plugins';
 import { immer, effects, autoActions, devtools } from '@modern-js/runtime/model';
@@ -38,4 +39,7 @@ AppWrapper = render();
 export default AppWrapper;;
 ```
 
-开发多页面应用的场景类似，在入口目录下推荐直接放置 `App.[jt]sx`, 自动生成的构建打包入口文件和单页面应用类似。
+
+:::note
+在多入口的场景下，每个入口都可以拥有独立的 `App.[jt]sx`，详见[入口](/docs/guides/concept/entries)。
+:::

package/zh/apis/app/hooks/src/index_.md

@@ -7,7 +7,7 @@ sidebar_position: 3
 
 通常情况下 [`src/App.[tj]sx, src/[entry]/App.[tj]sx`](/docs/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在 `bootstrap` 之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `index.[tj]s`。 下面有分两种情况进行讨论:
 
-1. bootstrap 之前添加自定义行为：
+1. 在 bootstrap 之前添加自定义行为：
 
 只需要 `src/index.[tj]s` 默认导出函数:
 

package/zh/apis/app/hooks/src/pages.md

@@ -3,11 +3,10 @@ title: pages/
 sidebar_position: 2
 ---
 
-应用项目基于文件系统路由的入口标识。
+应用使用基于文件系统路由时的入口标识。
 
 当项目结构为 `Pages 入口` 类型时， 会分析 `src/pages` 目录下的文件得到客户端路由配置。
 
-
 举例说明，例如以下目录结构：
 
 ```bash
@@ -94,7 +93,7 @@ export default const App = ({Component, ...pageProps}:{ Component: React.Compone
 }
 ```
 
-上述 `App` 为访问具体路由匹配到的组件。
+上述 `Component` 为访问具体路由匹配到的组件。
 
 例如以下目录结构:
 

package/zh/apis/app/hooks/src/stories.md

@@ -5,7 +5,7 @@ sidebar_position: 7
 
 应用项目 Storybook 调试文件。
 
-可以在项目源码目录(src)下创建 `*.stories.[tj]sx` 格式的文件作为 Storybook 的调试文件。
+可以在项目源码目录 `src/` 下创建 `*.stories.[tj]sx` 格式的文件作为 Storybook 的调试文件。
 
 在项目下执行 dev story 命令，支持使用这些文件在 Storybook 中对相关内容进行调试。
 

package/zh/apis/app/overview.md

@@ -3,7 +3,7 @@ sidebar_position: 0
 ---
 
 # 概览
-本节涵盖了使用 `@modern-js/app-tools` 的所有API。
+本节涵盖了使用 `@modern-js/app-tools` 的所有 API。
 
 import OverviewNav from '@site/src/components/OverviewNav';
 import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/api/framework/app.md

@@ -1,100 +0,0 @@
----
-title: app.[tj]s
-sidebar_position: 2
----
-
-Modern.js 框架写法下，该文件可以定制 API Server 的启动逻辑。在使用 `express`, `nest`, `koa` 时，该文件返回对应框架的实例。
-在使用 `egg` 框架时，该文件返回一个 Boot 类；与 `egg` 框架自身的[约定](https://eggjs.org/zh-cn/basics/app-start.html)相同。
-
-以下为简单示例：
-
-## [Express](https://expressjs.com/)
-
-```ts
-import express from 'express'
-
-const app = express();
-
-app.put('/user', function (req, res) {
-  res.send('Got a PUT request at /user')
-})
-
-app.use(async (req, res, next) => {
-    console.info(`access url: ${req.url}`);
-    next();
-});
-export default app
-```
-
-## [Nest](https://nestjs.com/)
-
-Nest 虽然有定制的启动器，但本质与 Express、Koa 相同，所以应用工程沿用了 Nest 定制启动器的默认入口：`api/main.ts`。
-
-按照 Nest 官方生成器生成的项目结构，在应用工程中使用 Nest 框架写法时，目录结构为：
-
-```markdown
-api
-├── app.controller.ts
-├── app.module.ts
-├── app.service.ts
-├── lambda
-│   └── hello.ts
-└── main.ts
-```
-
-其中 `api/main.ts` 中的内容与 Nest 官方生成器生成模版有所不同，应用工程中支持了两种模式：
-
-不包含内置 Module：
-
-```ts
-import { defineCustom } from '@modern-js/plugin-nest';
-import { NestFactory } from '@nestjs/core';
-import { Module } from '@nestjs/common';
-import { AppModule } from './app.module';
-
-export default NestFactory.create(AppModule);
-```
-
-包含内置 Module：
-
-```ts
-import { defineCustom } from '@modern-js/plugin-nest';
-import { NestFactory } from '@nestjs/core';
-import { Module } from '@nestjs/common';
-import { AppModule } from './app.module';
-
-export default defineCustom(async modules => {
-  @Module({
-    imports: [AppModule, ...modules],
-  })
-  class MainModule {}
-
-  return NestFactory.create(MainModule);
-});
-```
-
-## [Koa](https://koajs.com/)
-
-:::caution 注意
-当没有 `app.ts` 的时候，Modern.js 默认会添加 `koa-body`；当有 `app.ts` 时，需要你自己添加 `koa-body` 解析请求体。
-:::
-
-```ts
-import Koa from 'koa'
-import koaBody from 'koa-body'
-
-const app = new Koa();
-app.use(async (ctx, next) => {
-  console.info(`access url: ${ctx.url}`);
-  await next();
-});
-
-app.use(koaBody());
-
-export default app;
-```
-
-## [Egg](https://eggjs.org/)
-
-使用 Egg 框架时，同样在这个文件中可以自定义启动逻辑；
-但与其他框架不同，egg 中此文件遵循 egg 自身的[规范](https://eggjs.org/zh-cn/basics/app-start.html)，而不是 Modern.js 的约定。

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/eslint.md

@@ -1,9 +0,0 @@
----
-title: .eslintrc.json
-sidebar_position: 5
----
-
-Modern.js ESLint 全量规则集。
-
-具体规则信息请查看：[ESLint 全量规则集](/docs/guides/advanced-features/eslint)
-

package/zh/apis/app/hooks/api/framework/app.md

@@ -1,100 +0,0 @@
----
-title: app.[tj]s
-sidebar_position: 2
----
-
-Modern.js 框架写法下，该文件可以定制 API Server 的启动逻辑。在使用 `express`, `nest`, `koa` 时，该文件返回对应框架的实例。
-在使用 `egg` 框架时，该文件返回一个 Boot 类；与 `egg` 框架自身的[约定](https://eggjs.org/zh-cn/basics/app-start.html)相同。
-
-以下为简单示例：
-
-## [Express](https://expressjs.com/)
-
-```ts
-import express from 'express'
-
-const app = express();
-
-app.put('/user', function (req, res) {
-  res.send('Got a PUT request at /user')
-})
-
-app.use(async (req, res, next) => {
-    console.info(`access url: ${req.url}`);
-    next();
-});
-export default app
-```
-
-## [Nest](https://nestjs.com/)
-
-Nest 虽然有定制的启动器，但本质与 Express、Koa 相同，所以应用工程沿用了 Nest 定制启动器的默认入口：`api/main.ts`。
-
-按照 Nest 官方生成器生成的项目结构，在应用工程中使用 Nest 框架写法时，目录结构为：
-
-```markdown
-api
-├── app.controller.ts
-├── app.module.ts
-├── app.service.ts
-├── lambda
-│   └── hello.ts
-└── main.ts
-```
-
-其中 `api/main.ts` 中的内容与 Nest 官方生成器生成模版有所不同，应用工程中支持了两种模式：
-
-不包含内置 Module：
-
-```ts
-import { defineCustom } from '@modern-js/plugin-nest';
-import { NestFactory } from '@nestjs/core';
-import { Module } from '@nestjs/common';
-import { AppModule } from './app.module';
-
-export default NestFactory.create(AppModule);
-```
-
-包含内置 Module：
-
-```ts
-import { defineCustom } from '@modern-js/plugin-nest';
-import { NestFactory } from '@nestjs/core';
-import { Module } from '@nestjs/common';
-import { AppModule } from './app.module';
-
-export default defineCustom(async modules => {
-  @Module({
-    imports: [AppModule, ...modules],
-  })
-  class MainModule {}
-
-  return NestFactory.create(MainModule);
-});
-```
-
-## [Koa](https://koajs.com/)
-
-:::caution 注意
-当没有 `app.ts` 的时候，Modern.js 默认会添加 `koa-body`；当有 `app.ts` 时，需要你自己添加 `koa-body` 解析请求体。
-:::
-
-```ts
-import Koa from 'koa'
-import koaBody from 'koa-body'
-
-const app = new Koa();
-app.use(async (ctx, next) => {
-  console.info(`access url: ${ctx.url}`);
-  await next();
-});
-
-app.use(koaBody());
-
-export default app;
-```
-
-## [Egg](https://eggjs.org/)
-
-使用 Egg 框架时，同样在这个文件中可以自定义启动逻辑；
-但与其他框架不同，egg 中此文件遵循 egg 自身的[规范](https://eggjs.org/zh-cn/basics/app-start.html)，而不是 Modern.js 的约定。

package/zh/apis/app/hooks/src/eslint.md

@@ -1,9 +0,0 @@
----
-title: .eslintrc.json
-sidebar_position: 5
----
-
-Modern.js ESLint 全量规则集。
-
-具体规则信息请查看：[ESLint 全量规则集](/docs/guides/advanced-features/eslint)
-