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

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

@@ -0,0 +1,100 @@
+---
+title: api/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/api/framework/lambda.md

@@ -0,0 +1,79 @@
+---
+title: api/lambda/*.[tj]s
+sidebar_position: 1
+---
+
+声明 API 路由的文件，在 Modern.js 函数写法下；除了[某些约定文件](/docs/apis/app/hooks/api/framework/lambda#白名单)外，`api` 目录下的文件会被注册为接口的路由。
+
+:::info 注
+使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
+
+该文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
+:::
+
+## 路由规则
+
+### 默认路由
+
+路由系统会将以 `index` 命名的文件会被映射到上一层目录。
+
+* `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`
+
+### 动态路由
+
+同样的，你可以通过创建带有 `[xxx]` 的文件夹或者文件来支持动态的命名路由参数。
+
+* `api/lambda/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
+* `api/lambda/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
+* `api/lambda/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
+
+其中的 `$BASENAME` 可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
+
+### 白名单
+
+默认 `api` 目录下所有文件都会当作 BFF 函数文件去解析，但同样我们也设置了白名单，这些文件不被被解析：
+
+* 命名以 `_` 开头的文件。例如：`_utils.ts`。
+* 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
+* 测试文件。例如：`foo.test.ts`。
+* 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/_category_.json

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

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

@@ -0,0 +1,50 @@
+---
+title: api/**/*.[tj]s
+sidebar_position: 1
+---
+
+声明 API 路由的文件，在 Modern.js 函数写法下；除了[某些约定文件](/docs/apis/app/hooks/api/functions/api)外，`api` 目录下的文件会被注册为接口的路由。
+
+:::info 注
+使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
+
+该文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
+:::
+
+## 该文件约定路由如下：
+
+### 默认路由
+
+路由系统会将以 `index` 命名的文件会被映射到上一层目录。
+
+* `api/index.ts` -> `$BASENAME/`
+* `api/user/index.ts` -> `$BASENAME/user`
+
+### 嵌套路由
+
+路由系统也支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
+
+* `api/hello.ts` -> `$BASENAME/hello`
+* `api/user/list.ts` -> `$BASENAME/user/list`
+
+### 动态路由
+
+同样的，你可以通过创建带有 `[xxx]` 的文件夹或者文件来支持动态的命名路由参数。
+
+* `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
+* `api/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
+* `api/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
+
+其中的 `$BASENAME` 可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
+
+### 白名单
+
+默认 `api` 目录下所有文件都会当作 BFF 函数文件去解析，但同样我们也设置了白名单，这些文件不被被解析：
+
+* 命名以 `_` 开头的文件。例如：`_utils.ts`。
+* 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
+* 测试文件。例如：`foo.test.ts`。
+* TypeScript 类型文件。例如：`hello.d.ts`。
+* `node_module` 下的文件。
+
+

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

@@ -0,0 +1,10 @@
+---
+title: api/_app.[tj]s
+sidebar_position: 3
+---
+
+在 Modern.js 函数写法下，该文件可以给应用工程的服务端添加前置中间件；该中间件的执行会在[ BFF 函数](/docs/apis/app/hooks/api/functions/api)之前执行。
+
+目前 Modern.js 支持四种不同的框架，express，koa，nest，egg 等，不同的框架需要添加相应框架的中间件。具体示例请参考 [hook](/docs/apis/app/runtime/bff-server/hook)
+
+

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

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

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

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

package/zh/apis/app/hooks/config/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "config/",
+  "position": 6
+}

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

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

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

@@ -0,0 +1,17 @@
+---
+title: config/icon.png
+sidebar_position: 2
+---
+
+应用工程方案 App Icon 文件。
+
+项目根目录下 `config/icon.png` 时，可以在构建时在 html 页面注入 app icon 信息, 如下:
+
+```
+./config
+└── icon.png
+```
+
+最终 html 中会注入 app icon `link` 标签, 如下:
+
+![app-icon](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/api/app-icon.png)

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

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

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

@@ -0,0 +1,30 @@
+---
+title: config/public/
+sidebar_position: 3
+---
+
+应用工程方案静态资源文件。
+
+`public/` 目录中可以放置任意格式的静态资源文件，文件会被 Serve 在 Web 应用域名下。
+
+## 说明
+
+被 Serve 的文件路由基于目录结构的约定，其中，`public/` 为根目录，对应 Web 应用根域名。
+
+例如 `config/public/sdk/index.js` 文件，在部署后将会被 Serve 在 `${domain}/sdk/index.js` 下。
+
+## 场景
+
+例如 `robots.txt`，`auth.xml` 等第三方系统需要的认证文件。
+
+或者是给其他业务方（要求路由不变）的 SDK，也可以是无需入口的 HTML 文件等。
+
+:::info
+对于需要在源码中通过 import 引用的静态资源（比如 SVG 图片），建议放到 `src/assets` 目录下进行管理。
+:::
+
+## 代码压缩
+
+如果目录下的文件是一个 `.js` 文件，在生产环境构建时，会自动对其进行代码压缩。
+
+如果该文件以 `.min.js` 结尾，则不会经过代码压缩处理。

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

@@ -0,0 +1,14 @@
+---
+title: config/storybook/
+sidebar_position: 7
+---
+
+应用工程方案 Storybook 配置文件。
+
+应用工程方案支持使用 Storybook 进行调试，当需要对 Storybook 进行配置时，需要在项目 config/storybook 目录进行配置。
+
+Storybook 配置请查看：[Storybook 配置](https://storybook.js.org/docs/react/configure/overview)
+
+:::info 注
+使用 Storybook 进行调试需要提前在项目下执行 new 命令启用「Visual Testing (Storybook)」模式功能。
+:::

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

@@ -0,0 +1,48 @@
+---
+title: config/upload/
+sidebar_position: 4
+---
+
+应用工程方案静态资源文件。
+
+`upload/` 目录中可以放置任意格式的静态资源文件。
+
+## 说明
+
+在开发环境下，该目录下的静态资源文件会被托管在 `/upload` 路径下。构建应用产物后，该目录下的文件会被复制到产物目录中。
+
+该文件约定主要用于开发者使用插件，主动上传静态资源文件到 CDN。
+
+## 场景
+
+例如 `google-analysis.js` 等项目自用的 SDK（通常需要 http 缓存）。
+
+图片、字体文件、通用 CSS 等。
+
+如果并非必要，Modern.js 推荐将 JS / CSS 这类文件通过 `upload/` 上传到 CDN，而不使用 `public/`。
+
+## 代码压缩
+
+如果目录下的文件是一个 `.js` 文件，在生产环境构建时，会自动对其进行代码压缩。
+
+如果该文件以 `.min.js` 结尾，则不会经过代码压缩处理。
+
+## 更多用法
+
+不论是在[自定义 HTML](/docs/guides/basic-features/html) 中，或是在 [`config/public/`](/docs/apis/app/hooks/config/public) 下的任意 HTML 文件中，都可以直接使用 HTML 标签引用 `config/upload/` 目录下的资源：
+
+```html
+<script src="/upload/index.js"></script>
+```
+
+如果设置了 [`output.assetPrefix`](/docs/configure/app/output/asset-prefix) 前缀，也可以直接使用模板语法添加该前缀：
+
+```html
+<script src="<%=assetPrefix %>/upload/index.js"></script>
+```
+
+:::info 注
+Modern.js 没有支持在 `config/public/*.css`（例如 background-image）中通过 URL 使用 `config/upload/` 下的文件。
+
+因为 Modern.js 不推荐在 `public/` 中放 JS、CSS 这类资源文件，可以将它们直接放置在 `upload/` 目录下。
+:::

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

@@ -0,0 +1,12 @@
+---
+type: ref
+---
+
+# 文件约定
+
+本节涵盖了使用应用工程的所有文件约定。
+
+
+
+
+

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

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

package/zh/apis/app/hooks/server/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "server/",
+  "position": 3
+}

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

@@ -0,0 +1,14 @@
+---
+title: server/index.[tj]s
+sidebar_position: 1
+---
+
+扩展 Modern.js Server 的文件，在此文件中可以给应用工程启动的 Web Server 添加前置中间件。
+
+目前应用工程支持四种不同的框架中间件：Express、Koa、Egg、Nest，具体使用示例可查看 [hook](/docs/apis/app/runtime/web-server/hook)。
+
+可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等；也可在 Server 的运行流程中（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。
+
+:::info 注
+使用自定义 Server 需要在项目下执行 new 命令新建「Server 自定义」源码目录。
+:::

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

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

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

@@ -0,0 +1,8 @@
+---
+title: shared/
+sidebar_position: 5
+---
+
+应用工程方案共享源码目录。
+
+在项目中同时用到了 BFF 和自定义 Server 功能，并且它们之间存在一些公共服务端代码时，可将这些公共代码放到 shared 目录下。

package/zh/apis/app/hooks/src/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "src/",
+  "position": 1
+}

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

@@ -0,0 +1,41 @@
+---
+title: src/App.[tj]sx, src/[entry]/App.[tj]sx
+sidebar_position: 1
+---
+
+应用项目无路由或者任意路由的入口标识。
+
+开发单页面应用的场景，推荐 `src` 文件夹下放置 `App.[tj]sx` 导出应用根组件即可，Modern.js 会自动生成真正的构建打包的入口文件, 内容大致如下:
+
+```js
+import React from 'react';
+import { createApp, bootstrap } from '@modern-js/runtime';
+import App from '@_modern_js_src/App';
+import { state } from '@modern-js/runtime/plugins';
+import { immer, effects, autoActions, devtools } from '@modern-js/runtime/model';
+
+const createStatePlugins = (config) => {
+  const plugins = [];
+  plugins.push(immer(config['immer']));
+  plugins.push(effects(config['effects']));
+  plugins.push(autoActions(config['autoActions']));
+  plugins.push(devtools(config['devtools']));
+  return plugins;
+}
+let AppWrapper = null;
+function render() {
+  AppWrapper = createApp({
+    plugins: [
+     state({...{plugins: createStatePlugins(true)}, ...App?.config?.state}),
+    ]
+  })(App)
+  if (IS_BROWSER) {
+    bootstrap(AppWrapper, MOUNT_ID);
+  }
+  return AppWrapper
+}
+AppWrapper = render();
+export default AppWrapper;;
+```
+
+开发多页面应用的场景类似，在入口目录下推荐直接放置 `App.[jt]sx`, 自动生成的构建打包入口文件和单页面应用类似。

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

@@ -0,0 +1,10 @@
+---
+title: src/404/App.[tj]s,src/500/App.[tj]s,src/_error/App.[tj]s
+sidebar_position: 4
+---
+
+应用项目错误页面。
+
+Modern.js 约定将 `src/404/App.[tj]s` 为默认的 404 路由入口，`src/500/App.[tj]s`为默认 500 路由入口，`src/_error/App.[tj]s` 为默认错误路由入口。
+
+在服务端渲染的场景下，如果服务端出错，会根据 Error Code 返回对应路由的错误入口页面。

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

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

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

@@ -0,0 +1,35 @@
+---
+title: src/index.[tj]s, src/[entry]/index.[tj]s
+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 之前添加自定义行为：
+
+只需要 `src/index.[tj]s` 默认导出函数:
+
+```js title=src/index.js
+import { bootstrap } from '@modern-js/runtime';
+
+export default App => {
+  // do something before bootstrap...
+  bootstrap(App, 'root');
+};
+```
+
+
+2. 完全接管 webpack 入口:
+
+当 `src/index.[tj]sx?` 下没有默认导出函数时，该文件即为真正的 webpack 打包入口文件, 可以直接像使用 create-react-app 等脚手架一样组织代码:
+
+
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+
+ReactDOM.render(<App />, document.getElementById('root'));
+```