@modern-js/main-doc 2.0.0-beta.0 → 2.0.0-beta.1

package/zh/apis/app/runtime/web-server/hook.md

@@ -1,121 +1,131 @@
 ---
-sidebar_position: 3
+title: Hook
 ---
 
-# hook
+用于拓展 Modern.js 内置的 Web Server，非 BFF 请求会经过这些中 Hook 的处理。
 
-:::info 补充信息
-用于给 Web Server 添加中间件，发送给 Web Server 的请求会经过这些中间件的处理。
-```ts
-import { hook } from '@modern-js/runtime/server';
-```
+:::note
+更多内容可以查看[扩展 Web Server](/docs/guides/advanced-features/web-server)。
 :::
 
-## API
+## 使用姿势
 
-`hook(options) => void`
+```ts
+import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
 
-### 参数
+export const afterMatch: AfterMatchHook = (context, next) => {}
+export const afterRender: AfterRenderHook = (context, next) => {}
+```
 
-- options: `object`，Modern.js 提供的一系列钩子。
-  - [addMiddleware]: `string | function`，添加中间件的钩子。
+:::info 扩展 Web Server
+使用该 API 前，请先执行 `pnpm run new` 新建「Web Server 扩展」源码目录。
 
-## 示例
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「Web Server 扩展」源码目录
+```
+:::
+
+## 函数签名
 
-使用不同的框架，应添加不同框架的中间件；目前支持 express, nest, koa, egg 等框架。
+```ts
+type HookContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      get: (key: string) => string;
+      set: (key: string, value: string) => void;
+      delete: () => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+  };
+  request: {
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+};
+
+function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
+```
 
-### Express
+另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AtferMatch` 和 `AfterRender` 两个 Hook。
 
-```ts title=server/index.ts
-import { hook } from '@modern-js/runtime/server';
+```ts
+type AfterMatchContext = HookContext & {
+  router: {
+    redirect: (url: string, status: number) => void;
+    rewrite: (entry: string) => void;
+  };
+}
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (req, res, next) => {
-    req.query.id = 'express';
-    await next();
-  });
-});
+type AfterRenderContext = {
+  template: {
+    get: () => string;
+    set: (html: string) => void;
+    prependHead: (fragment: string) => void;
+    appendHead: (fragment: string) => void;
+    prependBody: (fragment: string) => void;
+    appendBody: (fragment: string) => void;
+  };
+};
 ```
 
-### Nest
 
-#### 添加中间件
+### 参数
 
-```ts title=server/index.ts
-import { hook } from '@modern-js/runtime/server';
+- `context`：提供当前 Hook 上下文。
+  - `response`：提供一系列处理响应的操作
+  - `request`：提供一系列获取请求信息的操作
+  - `router`：提供对响应路由的快捷操作
+  - `template`：提供对响应内容的快捷操作
+- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (req, res, next) => {
-    req.query.id = 'express';
-    await next();
-  });
-});
-```
+## 示例
 
-#### 添加 Module
-
-```ts title=server/index.ts
-import { hook } from '@modern-js/runtime/server';
-import {
-  Injectable,
-  MiddlewareConsumer,
-  Module,
-  NestMiddleware,
-} from '@nestjs/common';
-
-@Injectable()
-export class LoggerMiddleware implements NestMiddleware {
-  async use(req: any, res: any, next: any) {
-      console.info(`access url: ${req.url}`);
-      next();
-  }
-}
+### Redirect
 
-@Module()
-export class AppModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer.apply(LoggerMiddleware).forRoutes('*');
-  }
-}
+将页面重定向到站点外的页面，例如跳转到统一登录页：
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(AppModule);
-});
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.redirect('https://website.com/login', 302);
+};
 ```
 
-### Koa
+### Rewrite
 
-```ts title=server/index.ts
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (ctx, next) => {
-    ctx.req.query.id = 'koa';
-    await next();
-  });
-});
+将页面重写到当前站点的其他页面，例如同一个路由根据 UA 返回适配不同端的页面：
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.rewrite('mobile');
+};
 ```
 
-### egg
+### HTML 内容注入
 
-#### 添加中间件
+为页面注入某些与渲染主体无关的 HTML 内容，如脚本、页面骨架等：
 
-```ts title=server/index.ts
-export default hook(({ addMiddleware }) => {
-  addMiddleware(() => async (ctx, next) => {
-    ctx.req.query.id = 'egg';
-    await next();
-  });
-});
-```
+```ts
+import type { AfterRender } from '@modern-js/runtime/server';
 
-#### 给中间件注入参数
-
-```ts title=server/index.ts
-export default hook(({ addMiddleware }) => {
-  addMiddleware([
-    'eggMiddleware',        // 这里为第三方 node_module 包名
-    {
-      key: 'value',
-    },
-  ])
-});
+export const afterRender: AfterRenderHook = (context, next) => {
+  ctx.template.prependBody('<div>Footer</div>');
+}
 ```

package/zh/apis/app/runtime/web-server/middleware.md

@@ -0,0 +1,106 @@
+---
+title: Middleware
+---
+
+用于拓展 Modern.js 内置的 Web Server，只有 SSR 请求会经过这些中间件。
+
+与 [Hook](/docs/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以使用 Server 运行时框架拓展。
+
+:::note
+更多内容可以查看[扩展 Web Server](/docs/guides/advanced-features/web-server)。
+:::
+
+## 使用姿势
+
+```ts
+import { Middleware } from '@modern-js/runtime/server';
+
+export const middleware: Middleware = async (context, next) => {}
+export const middleware: Middleware[] = [
+  async (context, next) => {},
+  async (context, next) => {},
+]
+```
+
+:::info 扩展 Web Server
+使用该 API 前，请先执行 `pnpm run new` 新建「Web Server 扩展」源码目录。
+
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「Web Server 扩展」源码目录
+```
+:::
+
+## 函数签名
+
+```ts
+type MiddlewareContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      get: (key: string) => string;
+      set: (key: string, value: string) => void;
+      delete: () => void;
+      clear: () => void;
+      apply: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+    locals: Record<string, any>;
+  };
+  request: {
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+  source: {
+    req: IncomingMessage;
+    res: ServerResponse;
+  };
+};
+
+type RequestHandler = (context: Context, next: NextFunction) => Promise<void> | void;
+```
+
+
+### 参数
+
+- `context`：提供当前 Hook 上下文。
+  - `response`：提供一系列处理响应的操作
+  - `request`：提供一系列获取请求信息的操作
+  - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
+- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
+
+## 示例
+
+### 服务端耗时打点
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  const start = Date.now();
+  ctx.res.once('finish', () => {
+    console.log(Date.now() - start);
+  });
+}
+```
+
+### 注入服务端工具 & 数据
+
+Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量。
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  ctx.res.locals.id = 'Modern.js';
+  ctx.res.locals.rpc = createRpcInstance();
+});
+```
+

package/zh/apis/monorepo/commands/bump.md

@@ -37,6 +37,6 @@ npx modern bump
 
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />

package/zh/apis/monorepo/commands/change.md

@@ -53,6 +53,6 @@ $ npx modern change
 test publish
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />

package/zh/apis/monorepo/commands/clear.md

@@ -12,7 +12,7 @@ Options:
   -h, --help               display help for command
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />
 

package/zh/apis/monorepo/commands/deploy.md

@@ -12,7 +12,7 @@ Options:
   -h, --help         display help for command
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />
 

package/zh/apis/monorepo/commands/gen-release-note.md

@@ -30,6 +30,6 @@ Options:
 
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />

package/zh/apis/monorepo/commands/lint.md

@@ -12,7 +12,7 @@ Options:
   -h, --help  display help for command
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />
 

package/zh/apis/monorepo/commands/new.md

@@ -15,7 +15,7 @@ Options:
   -h, --help             display help for command
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />
 

package/zh/apis/monorepo/commands/pre.md

@@ -11,7 +11,7 @@ Options:
   -h, --help  display help for command
 ```
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />
 

package/zh/apis/monorepo/commands/release.md

@@ -15,6 +15,6 @@ Options:
 
 发布当前仓库的 Packages 至 NPM。
 
-import CommandTip from '@site/docs/components/command-tip.md'
+import CommandTip from '@site-docs/components/command-tip.md'
 
 <CommandTip />

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

@@ -1,6 +1,5 @@
 ---
 sidebar_label: fetcher
-sidebar_position: 2
 ---
 
 # bff.fetcher
@@ -13,7 +12,7 @@ sidebar_position: 2
   * Node.js 端：[node-fetch](https://github.com/node-fetch/node-fetch)
 
 :::caution 注意
-应用工程需要请确保使用【[new](/docs/apis/app/commands/new)】 启用了 BFF 功能。
+请先在当前应用项目根目录使用【[new](/docs/apis/app/commands/new)】 启用 BFF 功能。
 :::
 
 

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

@@ -1,6 +1,5 @@
 ---
 sidebar_label: prefix
-sidebar_position: 1
 ---
 
 # bff.prefix
@@ -11,7 +10,7 @@ sidebar_position: 1
 * 默认值：`/api`
 
 :::caution 注意
-应用工程需要请确保使用【[new](/docs/apis/app/commands/new)】 启用了 BFF 功能。
+请先在当前应用项目根目录使用【[new](/docs/apis/app/commands/new)】 启用 BFF 功能。
 :::
 
 默认情况下，BFF API 目录下的路由访问前缀是 `/api`, 如下目录结构：
@@ -26,7 +25,7 @@ api
 
 该配置选项可以修改默认的路由前缀：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   bff: {
     prefix: '/api-demo'

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

@@ -1,21 +1,18 @@
 ---
 sidebar_label: proxy
-sidebar_position: 1
 ---
 
 # bff.proxy
 
-
-
 * 类型：`Record<string, string>`
 * 默认值：`{}`
 
 :::info 补充信息
-应用工程需要请确保使用【[new](/docs/apis/app/commands/new)】 启用了 BFF 功能。
+请先在当前应用项目根目录使用【[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)。
+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` 中加入以下配置；即可开启代理：
 
@@ -29,11 +26,11 @@ export default defineConfig({
   }
 })
 ```
-假设启动的 Modern.js BFF server 的服务地址是`localhost:8080`，所有 path 以 `api` 开头的请求都会被拦截，如发送到 `localhost:8080/api/v1/topics` 的请求会被代理到 `https://cnodejs.org/api/v1/topics`。
+假设启动的 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"
+```typescript title="modern.server-runtime.config.ts"
 import { defineConfig } from '@modern-js/app-tools/server';
 export default defineConfig({
   bff: {
@@ -48,9 +45,7 @@ export default defineConfig({
 });
 ```
 
-与 [dev.proxy](/docs/configure/app/dev/proxy) 不同，本节所介绍的代理只作用于进入 BFF/API 服务的请求。
-
-同时，这一配置不但可以在开发环境中使用，在生产环境也会生成真实代码并且与项目一同部署。
+与 [dev.proxy](/docs/configure/app/dev/proxy) 不同，本节所介绍的代理只作用于进入 BFF/API 服务的请求；同时，这一配置不但可以在开发环境中使用，在生产环境中也会代理相应的请求。
 
 ## 常见用法
 
@@ -60,12 +55,12 @@ export default defineConfig({
 解决跨域问题的方式有很多，在这里我们使用 `bff.proxy` 可以轻松解决跨域问题。
 
 :::info 注
-BFF proxy 模式下，如果不需要写 BFF 的接口， API 目录可以删除；此时 BFF proxy仍会开启。
+BFF proxy 模式下，如果不需要写 BFF 的接口， API 目录可以删除；此时 BFF proxy 仍会开启。
 :::
 
-如下所示，在 `modern.server-runtime.config.js` 中，写入如下配置；我们将所有 web 页面发送到同域的以 `/api` 开头的请求代理到另一个域名的服务上。
+如下所示，在 `modern.server-runtime.config.ts` 中，写入如下配置；我们将所有 web 页面发送到同域的以 `/api` 开头的请求代理到另一个域名的服务上。
 
-```js title="modern.server-runtime.config.js"
+```typescript title="modern.server-runtime.config.ts"
 export default defineServerConfig({
   bff: {
     proxy: {

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

@@ -1,7 +1,6 @@
 ---
 title: dev.assetPrefix
 sidebar_label: assetPrefix
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: dev.hmr
 sidebar_label: hmr
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: dev.https
 sidebar_label: https
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: dev.port
 sidebar_label: port
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: dev.progressBar
 sidebar_label: progressBar
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,6 +1,5 @@
 ---
 sidebar_label: proxy
-sidebar_position: 1
 ---
 
 # dev.proxy
@@ -21,7 +20,7 @@ sidebar_position: 1
 
 例如：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   dev: {
     proxy: {
@@ -36,7 +35,7 @@ export default defineConfig({
 值为 `string` 时， 可以用来指定单独的代理文件，例如：
 
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   dev: {
     proxy: './proxy.js',

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

@@ -1,7 +1,6 @@
 ---
 title: dev.startUrl
 sidebar_label: startUrl
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,6 +1,5 @@
 ---
 sidebar_label: withMasterApp
-sidebar_position: 2
 ---
 
 # dev.withMasterApp

package/zh/configure/app/experiments/lazy-compilation.md

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

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

@@ -1,7 +1,6 @@
 ---
 title: html.appIcon
 sidebar_label: appIcon
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: html.crossorigin
 sidebar_label: crossorigin
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: html.disableHtmlFolder
 sidebar_label: disableHtmlFolder
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: html.faviconByEntries
 sidebar_label: faviconByEntries
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: html.favicon
 sidebar_label: favicon
-sidebar_position: 1
 ---
 
 :::info BUILDER

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

@@ -1,7 +1,6 @@
 ---
 title: html.injectByEntries
 sidebar_label: injectByEntries
-sidebar_position: 1
 ---
 
 :::info BUILDER