@modern-js/main-doc 2.1.0 → 2.3.0

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

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

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

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

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

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

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

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

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

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

@@ -1,17 +0,0 @@
----
-title: 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

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

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

@@ -1,28 +0,0 @@
----
-title: 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

@@ -1,12 +0,0 @@
----
-title: storybook/
-sidebar_position: 7
----
-
-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.md

@@ -1,42 +0,0 @@
----
-title: upload/
-sidebar_position: 4
----
-
-`upload/` 目录中可以放置任意格式的静态资源文件。
-
-## 说明
-
-在开发环境下，该目录下的静态资源文件会被托管在 `/upload` 路径下。构建应用产物后，该目录下的文件会被复制到产物目录中。
-
-该文件约定主要用于开发者使用插件，主动上传静态资源文件到 CDN。
-
-## 场景
-
-例如 `google-analysis.js` 等项目自用的 SDK（通常需要 http 缓存）。
-
-图片、字体文件、通用 CSS 等。
-
-## 代码压缩
-
-如果目录下的文件是一个 `.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/` 下的文件。
-:::

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

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

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

@@ -1,12 +0,0 @@
----
-title: index.[tj]s
-sidebar_position: 1
----
-
-扩展 Modern.js Web Server 的文件，在此文件中可以给应用工程启动的 Web Server 添加 Hook 或 Middleware。
-
-可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等。也可在内置处理逻辑（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。
-
-:::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

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

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

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

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

@@ -1,52 +0,0 @@
----
-title: App.[tj]sx
-sidebar_position: 1
----
-
-应用使用自控路由时的入口标识符。
-
-`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`，详见[入口](/docs/guides/concept/entries)。
-:::

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

@@ -1,34 +0,0 @@
----
-title: index.[tj]s
-sidebar_position: 4
----
-
-应用项目自定义路由入口标识。
-
-通常情况下 [`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 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.md

@@ -1,182 +0,0 @@
----
-title: pages/
-sidebar_position: 3
----
-
-应用使用基于文件系统路由时的入口标识。
-
-当项目结构为 `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`。

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

@@ -1,88 +0,0 @@
----
-title: routes/
-sidebar_position: 2
----
-
-应用使用基于文件系统路由时的入口标识。
-
-当项目结构为 `Routes 入口` 类型时， 会分析 `src/routes` 目录下的文件得到客户端路由配置。具体用法请查看[约定式路由](/docs/guides/basic-features/routes)
-
-任何在 `src/routes` 下的 `layout.[tj]sx` 和 `page.[tj]sx` 都会作为应用的路由：
-
-```bash {3}
-.
-└── routes
-    ├── layout.tsx
-    ├── page.tsx
-    └── user
-        ├── layout.tsx
-        └── page.tsx
-```
-
-## 基本示例
-
-`routes` 目录下的目录名会作为路由 url 的映射，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点，例如以下目录结构：
-
-```bash
-.
-└── routes
-    ├── page.tsx
-    └── user
-        └── page.tsx
-```
-
-会产出下面两条路由：
-
-- `/`
-- `/user`
-
-## 动态路由
-
-如果路由文件的目录名以 `[]` 命名，生成的路由会作为动态路由。例如以下文件目录：
-
-```
-└── routes
-    ├── [id]
-    │   └── page.tsx
-    ├── blog
-    │   └── page.tsx
-    └── page.tsx
-```
-
-`routes/[id]/page.tsx` 文件会转为 `/:id` 路由。除了可以确切匹配的 `/blog` 路由，其他所有 `/xxx` 都会匹配到该路由。
-
-在组件中，可以通过 [useParams](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
-
-在 loader 中，params 会作为 [loader](/docs/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params` 的属性可以获取到对应的参数。
-
-## 布局组件
-
-如下面的例子，可以通过添加 `layout.tsx`，为所有路由组件添加公共的布局组件：
-
-```bash
-.
-└── routes
-    ├── layout.tsx
-    ├── page.tsx
-    └── user
-        ├── layout.tsx
-        └── page.tsx
-```
-
-在布局组件中可以通过使用 `<Outlet>` 表示子组件：
-
-```tsx title=routes/layout.tsx
-import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
-
-export default () => {
-  return (
-    <>
-      <Outlet></Outlet>
-    </>
-  );
-};
-```
-
-:::note
-`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
-:::

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

@@ -1,33 +0,0 @@
----
-title: '*.[server|node].[tj]sx'
-sidebar_position: 8
----
-
-应用项目中使用，用于放置服务端代码，一般有以下两个作用：
-
-1. 当 `*.tsx` 和 `*.[server|node].tsx` 共存时，SSR 在服务端执行渲染时，会优先使用 `*.[server|node].tsx` 文件，而不是 `*.tsx` 文件。
-
-2. 在使用 [data loader](/docs/guides/basic-features/data-fetch) 时，需要将服务端的依赖从该文件中做重导出
-
-```tsx
-// routes/user/avatar.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-import { readFile } from './utils.server';
-
-type ProfileData = {
-  /* some type declarations */
-};
-
-export const loader = async (): ProfileData => {
-  const profile = await readFile('profile.json');
-  return profile;
-};
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-
-// routes/user/utils.server.ts
-export * from 'fs-extra';
-```

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

@@ -1,14 +0,0 @@
----
-title: '**/*.stories.[tj]sx'
-sidebar_position: 7
----
-
-应用项目 Storybook 调试文件。
-
-可以在项目源码目录 `src/` 下创建 `*.stories.[tj]sx` 格式的文件作为 Storybook 的调试文件。
-
-在项目下执行 dev story 命令，支持使用这些文件在 Storybook 中对相关内容进行调试。
-
-:::info 注
-使用 Storybook 需要提前在项目下执行 new 命令启用「Visual Testing (Storybook)」模式。
-:::