@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

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

@@ -0,0 +1,18 @@
+---
+sidebar_position: 8
+---
+# upgrade
+
+```
+Usage: modern upgrade [options]
+
+升级 Modern.js 到最新版本
+
+Options:
+  --registry <registry>  定制 npm registry (default: "")
+  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
+  --cwd <cwd>            项目路径 (default: "")
+  -h, --help             display help for command
+```
+
+在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。

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

@@ -0,0 +1,57 @@
+---
+title: lambda/*.[tj]s
+sidebar_position: 1
+---
+# lambda/*.[tj]s
+
+在 BFF 框架写法下，声明 API 路由的文件。除了[某些约定文件](/apis/app/hooks/api/framework/lambda#白名单)外，`api/` 目录下的文件会被注册为接口的路由。
+
+:::info
+使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
+
+:::
+
+:::tip
+该文件支持使用 `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` 下的文件。
+
+## 函数定义
+
+和函数写法下[函数定义](/apis/app/hooks/api/functions/api#define-function)完全一致。

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

@@ -0,0 +1,80 @@
+---
+title: '**/*.[tj]s'
+sidebar_position: 1
+---
+# **/*.[tj]s
+
+在 BFF 函数写法下，声明 API 路由的文件。除了[某些约定文件](/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` 下的文件。
+
+## 函数定义
+
+除了上面的路由规则之外，代码中函数定义与导出也有相应的约定。
+
+函数通过具名导出，导出函数的名字为对应接口接受的 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/app.mdx

@@ -0,0 +1,12 @@
+---
+title: _app.[tj]s
+sidebar_position: 3
+---
+# _app.[tj]s
+
+在函数写法下，该文件可以为 [BFF 函数](/apis/app/hooks/api/functions/api)添加前置中间件。
+
+:::note
+具体示例请参考 [hook](/apis/app/runtime/bff/hook)
+
+:::

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

@@ -0,0 +1,9 @@
+---
+title: '**/_*.[tj]s, _*/**'
+sidebar_position: 2
+---
+# **/_*.[tj]s, _*/**
+
+在 BFF 函数写法下，这些文件不会注册为路由。
+
+你可以在这种目录或文件下放任意项目中需要的代码，文件等。

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

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

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

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

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

@@ -0,0 +1,18 @@
+---
+title: icon.png
+sidebar_position: 2
+---
+# icon.png
+
+应用工程方案 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.mdx

@@ -0,0 +1,7 @@
+---
+title: mock/
+sidebar_position: 5
+---
+# mock/
+
+项目根目录下存在 `config/mock/index.js` 时，在开发环节自动开启 Mock 服务。

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

@@ -0,0 +1,30 @@
+---
+title: public/
+sidebar_position: 3
+---
+# public/
+
+`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.mdx

@@ -0,0 +1,14 @@
+---
+title: storybook/
+sidebar_position: 7
+---
+# storybook/
+
+Modern.js 支持使用 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.mdx

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,7 @@
+---
+title: shared/
+sidebar_position: 5
+---
+# shared/
+
+共享源码目录。当项目在 `api/`、`server/`、`src/` 下有公共代码时，可将这些代码放到 shared 目录下，而不是直接引用。

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

@@ -0,0 +1,54 @@
+---
+title: App.[tj]sx
+sidebar_position: 1
+---
+# App.[tj]sx
+
+应用使用自控路由时的入口标识符。
+
+`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';
+
+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;
+```
+
+:::note
+在多入口的场景下，每个入口都可以拥有独立的 `App.[jt]sx`，详见[入口](/guides/concept/entries)。
+
+:::

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

@@ -0,0 +1,35 @@
+---
+title: index.[tj]s
+sidebar_position: 4
+---
+# index.[tj]s
+
+应用项目自定义路由入口标识。
+
+通常情况下 [`src/App.[tj]sx, src/[entry]/App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在 `bootstrap` 之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `index.[tj]s`。 下面有分两种情况进行讨论:
+
+1. 在 bootstrap 之前添加自定义行为：
+
+只需要 `src/index.[tj]s` 默认导出函数:
+
+```js title=src/index.js
+import ReactDOM from 'react-dom/client';
+import { bootstrap } from '@modern-js/runtime';
+
+export default (App: React.ComponentType) => {
+  // do something before bootstrap...
+  bootstrap(App, 'root', undefined, ReactDOM);
+};
+```
+
+2. 完全接管 webpack 入口:
+
+当 `src/index.[tj]sx?` 下没有默认导出函数时，该文件即为真正的 webpack 打包入口文件, 可以直接像使用 create-react-app 等脚手架一样组织代码:
+
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```

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

@@ -0,0 +1,183 @@
+---
+title: pages/
+sidebar_position: 3
+---
+# pages/
+
+应用使用基于文件系统路由时的入口标识。
+
+当项目结构为 `Pages 入口` 类型时， 会分析 `src/pages` 目录下的文件得到客户端路由配置。
+
+举例说明，例如以下目录结构：
+
+```bash
+.
+└── src
+    └── pages
+        ├── about
+        │   └── index.jsx
+        ├── index.jsx
+        └── info.jsx
+```
+
+对应生成的路由配置为:
+
+```bash
+[
+  { path: '/', component: 'pages/index.jsx' },
+  { path: '/info' component: 'pages/info.jsx' },
+  { path: '/about', component: 'pages/about/index.jsx' }
+]
+```
+
+pages 目录下的文件满足以下条件的不会被当做路由文件
+
+- 后缀不是 `.(j|t)sx?` 的文件。
+- `.d.ts` 类型定义文件。
+- 以 `.(test|spec|e2e).(j|t)sx?` 结尾的测试文件。
+
+:::tip 提示
+
+推荐 pages 目录下只写入口代码，把业务逻辑写到 pages 外面独立的 features 目录里。这样 pages 目录下大部分文件都会是路由文件，也就不需要额外的过滤规则。
+
+:::
+
+### 动态路由
+
+使用 `[ ]` 包裹的目录或文件会被视为动态路由
+
+例如以下目录结构:
+
+```bash
+.
+└── src
+    └── pages
+        ├── [post]
+        │   ├── detail.jsx
+        │   └── index.js
+        ├── users
+        │   └── [id].jsx
+        ├── index.jsx
+        └── info.jsx
+```
+
+对应生成的路由配置为:
+
+```js
+[
+  { path: '/', component: 'pages/index.jsx' },
+  { path: '/info', component: 'pages/info.jsx' },
+  { path: '/:post/', component: 'pages/[post]/index.js' },
+  { path: '/:post/detail' components: 'pages/[post]/detail.jsx'},
+  { path: '/users/:id', components: 'pages/users/[id].jsx'}
+]
+```
+
+动态路由的基础上，支持添加特殊的路由后缀 `(*、?、+)`。
+
+例如：`src/pages/users/[id]*.tsx` 最终路由为 `/users/:id*`
+
+### 全局 layout
+
+整个应用需要全局的 `layout` 时， 可以通过 `pages/_app.tsx` 实现，具体写法如下:
+
+```js
+import React from 'react';
+import UserLayout from 'xxxx';
+
+export default const App = ({Component, ...pageProps}:{ Component: React.ComponentType}) => {
+  return (
+    <UserLayout>
+      <Component {...pageProps} />
+    </UserLayout>
+  );
+}
+```
+
+上述 `Component` 为访问具体路由匹配到的组件。
+
+例如以下目录结构:
+
+```bash
+.
+└── pages
+    ├── a
+    │   ├── b
+    │   │   └── index.js
+    │   └── index.js
+    └── index.js
+```
+
+- 访问 `/` 时，对应的 `Component` 组件为 `pages/index.js`。
+- 访问 `/a` 时，对应的 `Component` 组件为 `pages/a/index.js`。
+- 访问 `/a/b` 时，对应的 `Component` 组件为 `pages/a/b/index.js`。
+
+:::tip 全局 layout 有以下优点
+
+- 页面变化时，保留全局布局的状态
+- 添加全局样式
+- ComponentDidCatch 错误处理
+- 使用 `defineConfig`(/docs/apis/app/runtime/app/define-config) 动态配置运行时配置。
+
+:::
+
+### 部分 layout
+
+开发应用时，存在同一路由下的子路由共用 layout 的场景。
+
+针对这一场景，Modern.js 约定，当目录下存在 `_layout.js` ，就会有类似全局 layout 的效果。
+
+例如以下目录结构:
+
+```bash
+└── pages
+    ├── a
+    │   ├── b
+    │   │   └── index.js
+    │   ├── _layout.js
+    │   └── index.js
+    └── index.js
+```
+
+```js title="pages/a/_layout.js"
+import React from 'react';
+
+const ALayout = ({ Component, ...pageProps }) => {
+  return <Component {...pageProps} />;
+};
+export default ALayout;
+```
+
+Component 参数为访问具体路由对应的组件，例如
+
+- 访问 `/a` 时，对应的 `Component` 组件为 `pages/a/index.js`。
+- 访问 `/a/b` 时，对应的 `Component` 组件为 `pages/a/b/index.js`。
+
+这样就可以用 `pages/a/_layout.js` 满足 `a` 目录下路由共用 layout 的需求。
+
+### 404 路由
+
+约定 `pages/404.[tj]sx` 为默认的 404 路由。
+
+例如以下目录结构:
+
+```bash
+.
+└── src
+    └── pages
+        ├── user.js
+        ├── home.js
+        ├── 404.js
+```
+
+生成路由配置如下:
+
+```bash
+[
+ { path: '/user', component: './pages/user.js'},
+ { path: '/home', component: './pages/home.js' },
+ { path: '*', component: './pages/404.js'}
+]
+```
+
+所有未匹配的路由，都将匹配到 `pages/404.[tj]s`。