@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/guides/advanced-features/server-monitor/monitors.mdx

@@ -0,0 +1,240 @@
+# Monitors
+
+Modern.js 是一个全栈框架，它可以同时支持客户端和服务端的开发。当 Modern.js 在服务端渲染页面时，框架会在运行时插入更多日志与指标，帮助开发者在线上运维时定位问题。
+
+但服务端代码运行在 Node.js 环境中，开发者无法直接通过浏览器控制台来排查问题，而不同的项目可能使用不同的日志库，或是将数据上报到不同的平台。框架无法覆盖所有的场景，因此需要有统一的方式，允许开发者自行管理所有的内置日志与指标。
+
+Monitors 是 Modern.js 提供的帮助开发者监控应用程序的运行情况的模块。它包含注册 Monitor 和分发监控事件两部分能力。当开发者中调用 Monitors 的某个 API 时，框架会对应的监控事件分发到所有注册的 Monitor 中。
+
+:::note
+在 Modern.js 中内置了默认的 Monitor，开发者也可以注册自定义的 Monitor。
+:::
+
+## Monitors 定义
+
+Monitors 模块的类型定义如下，其中 `push` 方法用于注册 Monitor，其他方法用于分发监控事件。
+
+```ts
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+export interface LogEvent {
+  type: 'log';
+  payload: {
+    level: LogLevel;
+    message: string;
+    args?: any[];
+  };
+}
+
+export interface TimingEvent {
+  type: 'timing';
+  payload: {
+    name: string;
+    dur: number;
+    desc?: string;
+    args?: any[];
+  };
+}
+
+export interface CounterEvent {
+  type: 'counter';
+  payload: {
+    name: string;
+    args?: any[];
+  };
+}
+
+export type MonitorEvent = LogEvent | TimingEvent | CounterEvent;
+
+export type CoreMonitor = (event: MonitorEvent) => void;
+
+export interface Monitors {
+  // 注册 Monitor
+  push(monitor: CoreMonitor): void;
+
+  // 日志事件
+  error(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  trace(message: string, ...args: any[]): void;
+
+  // 指标事件
+  timing(name: string, dur: number, ...args: any[]): void;
+  counter(name: string, ...args: any[]): void;
+}
+```
+
+## 内置 Monitor
+
+Modern.js 内置了默认的 Monitor，不同的事件会触发内置 Monitor 不同的行为。详细内容查看：
+
+- [日志事件](/guides/advanced-features/server-monitor/logger)
+- [指标事件](/guides/advanced-features/server-monitor/metrics)
+
+## 注册 Monitors
+
+开发者可以通过 Monitors 的 `push` API 注册自己的 Monitor，但只能在[服务端中间件](/guides/advanced-features/web-server#unstable-middleware)或[服务端插件](/plugin/server-plugins/api)中注册，在 Data Loader、组件、init 函数中无法注册。
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
+
+const injectMonitorMiddleware: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const myMonitor = (event: MonitorEvent) => {
+    if (event.type === 'log') {
+      // 处理日志事件
+      console.log(`[${event.payload.level}] ${event.payload.message}`);
+    } else if (event.type === 'timing') {
+      // 处理性能指标事件
+      console.log(`Timing: ${event.payload.name} = ${event.payload.dur}ms`);
+    } else if (event.type === 'counter') {
+      // 处理计数事件
+      console.log(`Counter: ${event.payload.name}`);
+    }
+  };
+  monitors.push(myMonitor);
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'inject-monitor',
+      handler: injectMonitorMiddleware,
+    },
+  ],
+});
+```
+
+在服务端插件中注册 Monitor：
+
+```ts title="server/plugins/my-monitor-plugin.ts"
+import type { ServerPlugin } from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
+
+const myMonitorPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-monitor-plugin',
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+
+      // 定义 monitor，确保只创建一次
+      const myMonitor = (event: MonitorEvent) => {
+        if (event.type === 'log') {
+          // 处理日志事件
+          console.log(`[${event.payload.level}] ${event.payload.message}`);
+        } else if (event.type === 'timing') {
+          // 处理性能指标事件
+          console.log(`Timing: ${event.payload.name} = ${event.payload.dur}ms`);
+        } else if (event.type === 'counter') {
+          // 处理计数事件
+          console.log(`Counter: ${event.payload.name}`);
+        }
+      };
+
+      // 使用标志确保 monitor 只注册一次
+      let monitorRegistered = false;
+
+      middlewares.push({
+        name: 'inject-monitor',
+        handler: async (c, next) => {
+          const monitors = c.get('monitors');
+          // 只在第一次请求时注册 monitor
+          if (!monitorRegistered) {
+            monitors.push(myMonitor);
+            monitorRegistered = true;
+          }
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myMonitorPlugin;
+```
+
+然后在 `server/modern.server.ts` 中配置插件：
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import myMonitorPlugin from './plugins/my-monitor-plugin';
+
+export default defineServerConfig({
+  plugins: [myMonitorPlugin()],
+});
+```
+
+## 调用 Monitors
+
+Modern.js 允许开发者在 Data Loader、组件中调用 Monitors。
+
+:::tip
+只有在 Node.js 环境才可以调用 Monitors，在浏览器环境调用无任何效果。
+:::
+
+在 Data Loader 中，开发者可以这样使用：
+
+```ts title="routes/page.data.ts"
+import type { LoaderFunctionArgs } from '@modern-js/runtime/router';
+import { getMonitors } from '@modern-js/runtime';
+const loader = async ({ context }: LoaderFunctionArgs) => {
+    const monitors = getMonitors();
+    const start = Date.now();
+    try {
+        await fetch(...);
+        monitors.timing('loader_fetch_timing', Date.now() - start);
+    } catch(e) {
+        monitors.error(e);
+    }
+}
+```
+
+在组件中调用 Monitors，需要判断当前运行环境是否为 Node.js：
+
+```tsx title="routes/page.tsx"
+import { use } from 'react';
+import { RuntimeContext, getMonitors } from '@modern-js/runtime';
+const Page = () => {
+  const context = use(RuntimeContext);
+  if (process.env.MODERN_TARGET === 'node') {
+    const monitors = getMonitors();
+    monitors.info('Page rendered');
+  }
+  return <div>Hello World</div>;
+};
+export default Page;
+```
+
+在中间件中，我们也可以调用 Monitors，但方式与在运行时代码中不同，需要通过 `context` 来获取：
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  // 上报耗时
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
+```

package/docs/zh/guides/advanced-features/source-build.mdx

@@ -0,0 +1,168 @@
+---
+sidebar_position: 11
+---
+
+# 源码构建模式
+
+源码构建模式用于 monorepo 开发场景，它允许开发者直接引用 monorepo 中其他子项目的源码进行开发。
+
+## 使用场景
+
+**monorepo 中项目互相引用主要有产物引用和源码引用两种方式**。我们以一个最简单的 monorepo 为例子，来介绍源码引用的使用场景。
+
+比如 monorepo 中包含了一个 app 应用和一个 lib 包：
+
+```ts
+monorepo
+├── app
+└── lib
+    └── src
+        └── index.ts
+```
+
+其中，app 是基于 Modern.js 构建的，app 依赖了 lib 中的一些方法：
+
+```json
+{
+  "name": "app",
+  "dependencies": {
+    "lib": "workspace:*"
+  }
+}
+```
+
+### 产物引用
+
+**产物引用指的是当前项目引用其他子项目构建后的产物。**
+
+比如上述例子中的 lib 是使用 TypeScript 编写的，通常情况下，我们需要提前构建 lib 的代码，生成 JavaScript 产物，这样 app 才可以正确引用它。当 lib 代码更新时，还需要重新执行一次构建（或者使用 `tsgo --watch`），否则 app 无法引用到最新的代码。
+
+这种方式的优势在于：
+
+- 各个子项目的构建过程是完全独立的，可以拥有不同的构建配置。
+- 可以针对子项目进行构建缓存。
+
+劣势在于：
+
+- 本地开发时 HMR 的链路变长。
+- 当一个项目中包含多个 lib 包时，以上过程会显得十分繁琐。
+
+### 源码引用
+
+**源码引用指的是当前项目引用其他子项目的源码进行构建。**
+
+比如上述例子，当你开启了源码构建模式，并在 lib 中添加相关配置后，Modern.js 会自动引用 lib 的 `src/index.ts` 源代码。这意味着，你不需要提前构建 lib 的代码，并且当 lib 的源代码更新时，也可以自动触发 app 的热更新。
+
+这种方式的优势在于：
+
+- 子项目不依赖构建工具，也不需要添加构建配置，子项目的代码会被当前项目的构建工具编译。
+- 不需要提前执行子项目的构建流程。
+- 本地开发时 HMR 更高效。
+
+劣势在于：
+
+- 当前项目需要支持子项目用到的语法特性，并且遵循相同的语法规范，比如使用一致的装饰器语法版本。如果当前项目和子项目需要使用不同的编译配置，则不适合使用源码构建。
+- 当前项目需要编译更多的代码，因此构建时间可能会变长。
+
+## 使用源码构建
+
+### 开启配置
+
+你可以通过设置 [experiments.sourceBuild](/configure/app/experiments/source-build.html) 为 `true` 来开启源码构建模式。
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+### 配置子项目
+
+当开启源码构建模式后，Modern.js 在构建过程中，会优先读取子项目的 `source` 字段对应的文件。因此，你需要在子项目的 package.json 中配置 `source` 字段，并且指向源码文件路径。
+
+比如以下例子，当 lib 包被引用时，会读取 `./src/index.ts` 文件进行构建：
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+如果子项目使用了 [exports](https://nodejs.org/api/packages.html#package-entry-points) 配置，那么你同样需要在 `exports` 中增加 `source` 字段。
+
+```json title="package.json"
+{
+  "name": "lib",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## 配置 Project Reference
+
+在 TypeScript 项目中，你需要使用 TypeScript 提供的 [Project Reference](https://www.typescriptlang.org/docs/handbook/project-references.html) 能力，它可以帮助你更好地使用源码开发。
+
+### 介绍
+
+Project reference 提供了以下能力：
+
+- 使 TypeScript 可以正确识别其他子项目的类型，而无须对子项目进行构建。
+- 当你在 VS Code 内进行代码跳转时，VS Code 可以自动跳转到对应模块的源代码文件。
+- Modern.js 会读取 project reference 配置，并自动识别子项目的 `tsconfig.compilerOptions.path` 配置，从而让子项目的别名可以正确生效。
+
+### 示例
+
+在上文的例子中，由于 app 引用了 lib 子项目，我们需要在 app 的 `tsconfig.json` 内配置 `references`，并指向 lib 对应的相对目录：
+
+```json title="app/tsconfig.json"
+{
+  "references": [
+    {
+      "path": "../lib"
+    }
+  ]
+}
+```
+
+同时，需要在 lib 子项目的 `tsconfig.json` 内配置 `composite` 为 `true`：
+
+```json title="lib/A/tsconfig.json"
+{
+  "compilerOptions": {
+    "composite": true
+  },
+}
+```
+
+添加以上两个选项后，project reference 就已经配置完成了，你可以重新启动 VS Code 来查看配置以后的效果。
+
+注意以上只是一个最简单的例子，在实际的 monorepo 项目中，可能会有更复杂的依赖关系，你需要添加完整的 `references` 配置，才能使上述功能正确运作。
+
+:::tip
+如果你想了解更多关于 project reference 的内容，请阅读 [TypeScript - Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) 官方文档。
+:::
+
+## 注意事项
+
+在使用源码构建模式的时候，需要注意几点：
+
+1. 需要保证当前项目可以编译子项目里使用的语法或特性。比如子项目使用了 Stylus 来编写 CSS 样式，那就需要当前 app 支持 Stylus 编译。
+2. 需要保证当前项目与子项目使用的代码语法特性相同，例如装饰器的语法版本一致。
+3. 源码构建可能存在一些限制。如果在使用中遇到问题，你可以将子项目 package.json 中的 `source` 字段移除，使用子项目的构建产物进行调试。
+4. 开启 `composite: true` 后，TypeScript 会生成 `*.tsbuildinfo` 临时文件，你需要将这些临时文件加入 .gitignore 中。
+
+```text title=".gitignore"
+*.tsbuildinfo
+```

package/docs/zh/guides/advanced-features/web-server.mdx

@@ -0,0 +1,281 @@
+---
+sidebar_position: 16
+---
+
+# 自定义 Web Server
+
+Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
+
+要在 Modern.js 项目中使用自定义 Web Server，请按照以下步骤操作：
+
+1. 安装 `@modern-js/server-runtime` 依赖
+
+如果项目尚未安装 `@modern-js/server-runtime` 依赖，请先安装：
+
+```bash
+pnpm add @modern-js/server-runtime
+```
+
+:::tip 版本一致性
+请确保 `@modern-js/server-runtime` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
+
+请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/server-runtime`：
+
+```bash
+# 查看当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<版本号>
+```
+
+:::
+
+2. 创建 `server` 目录和配置文件
+
+在项目根目录下创建 `server/modern.server.ts` 文件：
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [], // 中间件
+  renderMiddlewares: [], // 渲染中间件
+  plugins: [], // 插件
+  onError: () => {}, // 错误处理
+});
+```
+
+创建文件后，可以在这个文件中编写自定义逻辑。
+
+## 自定义 Web Server 能力
+
+Modern.js 的服务器基于 Hono 实现，在最新版本的自定义 Web Server 中，我们向用户暴露了 Hono 的中间件能力，你可以参考 [Hono 文档](https://hono.dev/docs/api/context) 了解更多用法。
+
+`server/modern.server.ts` 文件中添加如下配置来扩展 Server：
+
+- **中间件（Middleware）**
+- **渲染中间件（RenderMiddleware）**
+- **服务端插件（Plugin）**
+
+其中 **Plugin** 中可以定义 **Middleware** 与 **RenderMiddleware**。 中间件加载流程如下图所示：
+
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/10eh7nuhpenuhog/server-md-wf.png"
+  style={{ width: '100%', maxWidth: '540px' }}
+/>
+
+### 基本配置
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [], // 中间件
+  renderMiddlewares: [], // 渲染中间件
+  plugins: [], // 插件
+  onError: () => {}, // 错误处理
+});
+```
+
+### 类型定义
+
+`defineServerConfig` 类型定义如下:
+
+```ts
+import type { MiddlewareHandler } from 'hono';
+
+type MiddlewareObj = {
+  name: string;
+  path?: string;
+  method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
+  handler: MiddlewareHandler | MiddlewareHandler[];
+};
+type ServerConfig = {
+  middlewares?: MiddlewareObj[];
+  renderMiddlewares?: MiddlewareObj[];
+  plugins?: ServerPlugin[];
+  onError?: (err: Error, c: Context) => Promise<any> | any;
+};
+```
+
+### Middleware
+
+Middleware 支持在 Modern.js 服务的**请求处理**与**页面路由**的流程前后，执行自定义逻辑。
+即自定义逻辑既要处理接口路由，也要作用于页面路由，那么 Middleware 是不二选择。
+
+:::note
+如果仅需要处理 BFF 接口路由，可以通过检查 `req.path` 是否以 BFF `prefix` 开头，来判断是否为 BFF 接口请求。
+:::
+
+使用姿势如下：
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  // 上报耗时
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
+```
+
+:::warning
+必须执行 `next` 函数才会执行后续的 Middleware。
+:::
+
+### RenderMiddleware
+
+如果只需要处理页面渲染的前后执行逻辑，modern.js 也提供了渲染中间件，使用姿势如下：
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+// 注入 render 性能指标
+const renderTiming: MiddlewareHandler = async (c, next) => {
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  c.res.headers.set('server-timing', `render; dur=${end - start}`);
+};
+
+// 修改响应体
+const modifyResBody: MiddlewareHandler = async (c, next) => {
+  await next();
+
+  const { res } = c;
+  const text = await res.text();
+  const newText = text.replace('<body>', '<body> <h3>bytedance</h3>');
+
+  c.res = c.body(newText, {
+    status: res.status,
+    headers: res.headers,
+  });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [
+    {
+      name: 'render-timing',
+      handler: renderTiming,
+    },
+    {
+      name: 'modify-res-body',
+      handler: modifyResBody,
+    },
+  ],
+});
+```
+
+### Plugin
+
+Modern.js 支持在自定义插件中为 Server 添加上述 Middleware 及 RenderMiddleware，使用姿势如下：
+
+```ts title="server/plugins/server.ts"
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+export default (): ServerPlugin => ({
+  name: 'serverPlugin',
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares, renderMiddlewares } = api.getServerContext();
+
+      // 注入服务端数据，供页面 dataLoader 消费
+      middlewares?.push({
+        name: 'server-plugin-middleware',
+        handler: async (c, next) => {
+          c.set('message', 'hi modern.js');
+          await next();
+          // ...
+        },
+      });
+
+      // 重定向
+      renderMiddlewares?.push({
+        name: 'server-plugin-render-middleware',
+        handler: async (c, next) => {
+          const user = getUser(c.req);
+          if (!user) {
+            return c.redirect('/login');
+          }
+
+          await next();
+        },
+      });
+    });
+  },
+});
+```
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import serverPlugin from './plugins/serverPlugin';
+
+export default defineServerConfig({
+  plugins: [serverPlugin()],
+});
+```
+
+```ts title="src/routes/page.data.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const ctx = useHonoContext();
+  // SSR 场景消费服务端注入的数据
+  const message = ctx.get('message');
+
+  // ...
+};
+```
+
+### onError
+
+`onError` 是一个全局错误处理函数，用于捕获和处理 Modern.js server 中的所有未捕获错误。通过自定义 `onError` 函数，开发者可以统一处理不同类型的错误，返回自定义的错误响应，实现错误日志记录、错误分类处理等功能。
+
+以下是一个基本的 `onError` 配置示例：
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  onError: (err, c) => {
+    // 记录错误日志
+    console.error('Server error:', err);
+
+    // 根据不同的错误类型返回不同的响应
+    if (err instanceof SyntaxError) {
+      return c.json({ error: 'Invalid JSON' }, 400);
+    }
+
+    // 根据请求路径定制 bff 异常响应
+    if (c.req.path.includes('/api')) {
+      return c.json({ message: 'API error occurred' }, 500);
+    }
+
+    return c.text('Internal Server Error', 500);
+  },
+});
+```