@modern-js/main-doc 2.65.1 → 2.65.3

package/docs/en/components/internal-logger.mdx

@@ -0,0 +1,25 @@
+In Modern.js, log events are handled by `LoggerMonitor`, which outputs logs to the console.
+
+:::info
+The built-in `LoggerMonitor` depends on the [rslog](https://www.npmjs.com/package/rslog) library.
+:::
+
+For example, intentionally throwing an error in the project:
+
+```tsx title=routes/page.tsx
+import './index.css';
+
+const Index = () => <div className="container-box">{a}</div>;
+
+export default Index;
+```
+
+If running normally, you can see the following output in the console:
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+error   SSR Error - App Prerender, error = ReferenceError: a is not defined
+    at Index (/somepath/page.tsx:3:1)
+```

package/docs/en/components/internal-metrics.mdx

@@ -0,0 +1,20 @@
+In Modern.js, metric events are also handled by `LoggerMonitor`, which outputs metrics to the console in a specific format.
+
+:::info
+The built-in `LoggerMonitor` depends on the [rslog](https://www.npmjs.com/package/rslog) library.
+:::
+
+The `rslog` instance initialized in Modern.js outputs logs at `debug` level and above in development environment by default, and outputs all logs in production environment. In the built-in `LoggerMonitor`, all metric events are output as Debug logs. Therefore, if you want to view metric event information in the development environment, you need to add additional environment variables.
+
+Developers can add the environment variable `DEBUG=true` when running the `dev` command. If running normally, after accessing, you can see the following output in the console:
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+debug   SSR Debug - server-loader, cost: 2.000094, req.url = /
+debug   SSR Debug - ssr-prerender, cost: 6.99997, req.url = /
+debug   SSR Debug - ssr-render-html, cost: 0.999927, req.url = /
+debug   Debug - server-handle-request, cost: 19.999981, req.url = /
+debug     --> GET / 200 90ms
+```

package/docs/en/configure/app/runtime/master-app.mdx

@@ -37,4 +37,4 @@ interface AppInfo {
 
 In the `masterApp` configuration, developers can pass through options supported by Garfish
 
-All supported configuration options [see here](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0).
+All supported configuration options [see here](https://www.garfishjs.org/api/run.html).

package/docs/en/guides/advanced-features/_meta.json

@@ -6,6 +6,7 @@
     "label": "use-bff",
     "collapsed": true
   },
+
   {
     "type": "dir",
     "name": "page-performance",
@@ -16,5 +17,11 @@
   "compatibility",
   "low-level",
   "source-build",
+  {
+    "type": "dir",
+    "name": "server-monitor",
+    "label": "server-monitor",
+    "collapsed": true
+  },
   "web-server"
 ]

package/docs/en/guides/advanced-features/server-monitor/_meta.json

@@ -0,0 +1 @@
+["monitors", "logger", "metrics"]

package/docs/en/guides/advanced-features/server-monitor/logger.mdx

@@ -0,0 +1,30 @@
+# Logs Events
+
+Log events are distributed by Modern.js as events of type `log`.
+
+## Built-in Events
+
+Based on server-side runtime logic, Modern.js provides the following log events:
+
+| Stage           | Message                                      | Level |
+| --------------- | -------------------------------------------- | ----- |
+| RENDER_HTML     | App Render To HTML                           | error |
+| RENDER_STREAM   | An error occurs during streaming SSR         | error |
+| RENDER_SHELL    | An error occurs during streaming render shell | error |
+
+Modern.js also retains SSR logs from legacy versions using `useLoader`:
+
+| Stage         | Message                         | Level |
+| ------------- | ------------------------------- | ----- |
+| PRERENDER     | App Prerender                   | error |
+| USE_LOADER    | App run useLoader               | error |
+
+:::tip
+The `useLoader` API is now deprecated. We recommend migrating to convention-based routing and using Data Loaders for data fetching. Applications already using Data Loaders can enable [`ssr.disablePrerender`](/configure/app/server/ssr.html#object-type) to disable prerendering and improve SSR performance.
+:::
+
+## Built-in Monitor
+
+import InternalLogger from '@site-docs-en/components/internal-logger.mdx';
+
+<InternalLogger />

package/docs/en/guides/advanced-features/server-monitor/metrics.mdx

@@ -0,0 +1,41 @@
+# Metrics Events
+
+Metric events are distributed by Monitors as events of type `timing` or `counter`.
+
+## Built-in Events
+
+When SSR is enabled, we need to monitor server-side phase durations and have the capability to diagnose server-side issues.
+
+Based on server-side runtime logic, Modern.js provides the following metric events:
+
+| Key                      | Description              |
+| ------------------------ | ------------------------ |
+| server-handle-request    | EdenX Server request handling duration                          |
+| ssr-render-shell         | [SSR] When using Streaming SSR, React renders a shell for early streaming. This marks shell rendering completion time |
+| ssr-render-html          | [SSR] Time taken by React to render component tree to HTML (typically under 50ms) |
+| server-middleware        | Total execution time of EdenX custom server middlewares         |
+| server-loader            | Server-side Data Loader total duration                          |
+| server-loader-#id        | Individual Data Loader durations on server-side                 |
+| server-loader-navigation | Server-side Data Loader duration during client navigation       |
+
+Modern.js server workflow diagram:
+
+![server](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/edenx-website/e374def0-c179-40aa-9cfe-e82e181663b1.jpeg)
+
+## Built-in Monitor
+
+import InternalMetrics from '@site-docs-en/components/internal-metrics.mdx';
+
+<InternalMetrics />
+
+## Server-Timing
+
+Modern.js injects phase metrics as Server-Timing headers into HTML responses.
+
+Developers can retrieve these metrics using the [Performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance) in browsers:
+
+```ts
+const navigation = performance.getEntriesByType('navigation')[0];
+const serverTiming = navigation.serverTiming;
+console.log(serverTiming);
+```

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

@@ -0,0 +1,157 @@
+# Monitors
+
+Modern.js is a full-stack framework that supports both client-side and server-side development. When server-side rendering (SSR), the framework automatically injects additional logs and metrics during server runtime to help production issue diagnosis.
+
+As server code operates in Node.js environments, developers cannot directly utilize browser consoles for troubleshooting. Given that different projects may adopt varied logging libraries or data reporting platforms, the framework provides a unified approach for developers to manage built-in logging and metric collection.
+
+The Monitors module in Modern.js empowers application monitoring through two core capabilities: Monitor registration and monitoring event distribution. When developers invoke Monitors APIs, the framework propagates corresponding monitoring events to all registered Monitors.
+
+:::note
+Modern.js ships with a default Monitor implementation, while simultaneously allowing developers to register custom Monitors.
+:::
+
+## Monitors Type
+
+The Monitors module is defined with the following types, where the `push` method is used to register Monitor and other methods are used to dispatch monitoring events.
+
+```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 {
+  // Register Monitor
+  push(monitor: CoreMonitor): void;
+
+  // Log Event
+  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;
+
+  // Metrics Event
+  timing(name: string, dur: number, ...args: any[]): void;
+  counter(name: string, ...args: any[]): void
+}
+```
+
+## Internal Monitor
+
+Modern.js comes with a built-in default Monitor, where different events trigger different behaviors in the built-in Monitor. For more details, see:
+
+- [Log Event](/guides/advanced-features/server-monitor/logger)
+- [Metrics Event](/guides/advanced-features/server-monitor/metrics)
+
+
+## Register Monitors
+
+Developers can register their own Monitors using the `push` API, but this can only be done in [server middleware](/apis/app/runtime/web-server/unstable_middleware) or server plugins. Registration is not available in Data Loaders, components, or init functions.
+
+:::note
+Server plugins are currently not available, and documentation will be added in the future.
+:::
+
+```ts title="server/index.ts"
+import type { CoreMonitors } from '@modern-js/types';
+const injectMonitorMiddleware = (c) => {
+    const monitors = c.get('monitors');
+    const myMonitor = (event: MonitorEvent) => {
+        if (event.type === 'log') {
+          // some code
+        } else {
+          // some other code
+        }
+    }
+    monitors.push(myMonitor);
+    return next();
+}
+
+export const middlewares = [injectMonitorMiddleware]
+```
+
+## Use Monitors
+
+Modern.js allows developers to invoke Monitors in Data Loaders and components.
+
+:::tip
+Monitors can only be invoked in Node.js environments, and calling them in browser environments will have no effect.
+:::
+
+In Data Loaders, developers can use them as follows:
+
+```ts title="routes/page.data.ts"
+import { 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);
+    }
+}
+```
+
+When invoking Monitors in components, you need to determine whether the current runtime environment is Node.js:
+
+```tsx title="routes/page.tsx"
+import { getMonitors } from '@modern-js/runtime';
+const Page = () => {
+    const { context } = useRuntimeContext();
+    if (process.env.MODERN_TARGET === 'node') {
+        const monitors = getMonitors();
+        monitors.info();
+    }
+    return <div>Hello World</div>
+}
+export default Page;
+```
+
+In middleware, we can also invoke Monitors, but the approach differs from runtime code as it requires accessing them through `context`:
+
+```ts title="server/index.ts"
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+const time: UnstableMiddleware = async (c, next) => {
+  const start = Date.now();
+  await next();
+  const end = Date.now();
+  const monitors = c.get('monitors');
+  monitors.info(`${end - start}`);
+};
+
+export const unstableMiddleware: UnstableMiddleware[] = [time];
+```
+
+

package/docs/en/guides/basic-features/data/_meta.json

@@ -1 +1 @@
-["data-fetch", "data-write"]
+["data-fetch", "data-write", "data-cache"]

package/docs/en/guides/basic-features/data/data-cache.mdx

@@ -0,0 +1,169 @@
+---
+title: Data Caching
+sidebar_position: 4
+---
+# Data Caching
+
+The `cache` function allows you to cache the results of data fetching or computation.
+
+## Basic Usage
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser(user); // When the parameters of the function changes, the function will be re-executed
+  return {
+    user,
+  };
+};
+```
+
+
+### Parameters
+
+- `fn`: The data fetching or computation function to be cached
+- `options` (optional): Cache configuration
+  - `tag`: Tag to identify the cache, which can be used to invalidate the cache
+  - `maxAge`: Cache validity period (milliseconds)
+  - `revalidate`: Time window for revalidating the cache (milliseconds), similar to HTTP Cache-Control's stale-while-revalidate functionality
+
+The type of the `options` parameter is as follows:
+
+```ts
+interface CacheOptions {
+  tag?: string | string[];
+  maxAge?: number;
+  revalidate?: number;
+}
+```
+
+
+### Return Value
+
+The `cache` function returns a new function with caching capabilities. Multiple calls to this function will not re-execute the `fn` function.
+
+## Usage Scope
+
+Unlike React's [cache](https://react.dev/reference/react/cache) function which can only be used in server components,
+EdenX's `cache` function can be used in any frontend or server-side code.
+
+## Detailed Usage
+
+### Without `options` Parameter
+
+When no `options` parameter is provided, it's primarily useful in SSR projects, the cache lifecycle is limited to a single SSR rendering request. For example, when the same cachedFn is called in multiple data loaders, the cachedFn function won't be executed repeatedly. This allows data sharing between different data loaders while avoiding duplicate requests. EdenX will re-execute the `fn` function with each server request.
+
+:::info
+Without the `options` parameter, it can be considered a replacement for React's [`cache`](https://react.dev/reference/react/cache) function and can be used in any server-side code (such as in data loaders of SSR projects), not limited to server components.
+:::
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser();
+  return {
+    user,
+  };
+};
+```
+
+
+### With `options` Parameter
+
+#### `maxAge` Parameter
+
+After each computation, the framework records the time when the cache is written.
+When the function is called again, it checks if the cache has expired based on the `maxAge` parameter.
+If expired, the `fn` function is re-executed; otherwise, the cached data is returned.
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,  // Calling this function within 2 minutes will return cached data
+  }
+);
+```
+
+
+#### `revalidate` Parameter
+
+The `revalidate` parameter sets a time window for revalidating the cache after it expires. It can be used together with the `maxAge` parameter, similar to HTTP Cache-Control's stale-while-revalidate mode.
+
+In the following example, within the 2-minute period before the cache expires, calls to `getDashboardStats` will return cached data. If the cache has expired (between 2 and 3 minutes), requests will first return the old data, then refresh the data in the background and update the cache.
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,
+    revalidate: CacheTime.MINUTE * 1,
+  }
+);
+```
+
+
+#### `tag` Parameter
+
+The `tag` parameter identifies the cache with a tag, which can be a string or an array of strings.
+You can invalidate caches based on this tag, and multiple cache functions can use the same tag.
+
+```ts
+import { cache, revalidateTag } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchDashboardStats();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+const getComplexStatistics = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+revalidateTag('dashboard-stats'); // Invalidates the cache for both getDashboardStats and getComplexStatistics functions
+```
+
+
+### Storage
+
+Currently, both client and server caches are stored in memory.
+The default storage limit for all cached functions is 1GB. When this limit is reached, the oldest cache is removed using an LRU algorithm.
+
+:::info
+Considering that the results of `cache` function caching are not large, they are currently stored in memory by default.
+:::
+
+You can specify the storage limit using the `configureCache` function:
+
+```ts
+import { configureCache, CacheSize } from '@modern-js/runtime/cache';
+
+configureCache({
+  maxSize: CacheSize.MB * 10, // 10MB
+});
+```

package/docs/zh/components/internal-logger.mdx

@@ -0,0 +1,25 @@
+在 Modern.js 中，日志事件由 LoggerMonitor 处理，它会将日志输出到控制台。
+
+:::info
+内置的 LoggerMonitor 依赖了 [rslog](https://www.npmjs.com/package/rslog) 库。
+:::
+
+例如在项目中有意的抛出一个错误：
+
+```tsx title=routes/page.tsx
+import './index.css';
+
+const Index = () => <div className="container-box">{a}</div>;
+
+export default Index;
+```
+
+如果运行正常，可以在控制台看到如下输出：
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+error   SSR Error - App Prerender, error = ReferenceError: a is not defined
+    at Index (/somepath/page.tsx:3:1)
+```

package/docs/zh/components/internal-metrics.mdx

@@ -0,0 +1,20 @@
+在 Modern.js 中，指标事件也由 LoggerMonitor 处理，它会将指标按照一定格式输出到控制台。
+
+:::info
+内置的 LoggerMonitor 依赖了 [rslog](https://www.npmjs.com/package/rslog) 库。
+:::
+
+在 Modern.js 中初始化的 `rslog` 实例默认在开发环境下会输出 `debug` 级别及以上的日志，在生产环境下会输出所有日志。而在内置的 `LoggerMonitor` 中，所有的指标事件都被输出为 Debug 日志。因此如果希望在开发环境查看指标事件的信息，需要添加额外的环境变量。
+
+开发者可以在运行 `dev` 命令时添加环境变量 `DEBUG=true`，如果运行正常，访问后可以在控制台看到如下输出：
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+debug   SSR Debug - server-loader, cost: 2.000094, req.url = /
+debug   SSR Debug - ssr-prerender, cost: 6.99997, req.url = /
+debug   SSR Debug - ssr-render-html, cost: 0.999927, req.url = /
+debug   Debug - server-handle-request, cost: 19.999981, req.url = /
+debug     --> GET / 200 90ms
+```

package/docs/zh/configure/app/runtime/master-app.mdx

@@ -39,4 +39,4 @@ interface AppInfo {
 
 在 `masterApp` 配置下，开发者可以透传 Garfish 的配置项。
 
-所有支持的配置项[点此查看](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0)。
+所有支持的配置项[点此查看](https://www.garfishjs.org/api/run.html)。

package/docs/zh/guides/advanced-features/_meta.json

@@ -6,6 +6,7 @@
     "label": "use-bff",
     "collapsed": true
   },
+
   {
     "type": "dir",
     "name": "page-performance",
@@ -16,5 +17,11 @@
   "compatibility",
   "low-level",
   "source-build",
+  {
+    "type": "dir",
+    "name": "server-monitor",
+    "label": "server-monitor",
+    "collapsed": true
+  },
   "web-server"
 ]

package/docs/zh/guides/advanced-features/server-monitor/_meta.json

@@ -0,0 +1 @@
+["monitors", "logger", "metrics"]

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

@@ -0,0 +1,32 @@
+# 日志事件
+
+日志事件是由 Modern.js 分发的，类型为 `log` 的事件。
+
+## 内置事件
+
+基于服务端运行逻辑，Modern.js 在内部提供了以下日志事件：
+
+| 阶段          | 消息                                         | Level |
+| ------------- | -------------------------------------------- | ----- |
+| RENDER_HTML   | App Render To HTML                           | error |
+| RENDER_STREAM | An error occurs during streaming SSR         | error |
+| RENDER_SHELL  | An error occurs during streaming render shell | error |
+
+Modern.js 也保留了旧版本中使用 `useLoader` 获取数据时的 SSR 日志：
+
+| 阶段          | 消息                                         | Level |
+| ------------- | -------------------------------------------- | ----- |
+| PRERENDER   | App Prerender                          | error |
+| USE_LOADER | App run useLoader         | error |
+
+:::tip
+`useLoader` API 目前已经废弃，建议迁移到约定式路由并使用 Data Loader 进行数据获取。已经使用 Data Loader 的应用，可以开启 [`ssr.disablePrerender`](/configure/app/server/ssr.html#object-类型)，禁止预渲染，提升 SSR 性能。
+:::
+
+## 内置 Monitor
+
+import InternalLogger from '@site-docs/components/internal-logger.mdx';
+
+<InternalLogger />
+
+

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

@@ -0,0 +1,42 @@
+# 指标事件
+
+指标事件是由 Monitors 分发，类型为 `timing` 或 `counter` 的事件。
+
+## 内置事件
+
+当项目开启 SSR 时，我们需要关注 Server 端各阶段耗时，并且有能力对 Server 端的问题进行定位。
+
+基于服务端运行逻辑，Modern.js 在内部提供了以下指标事件：
+
+| Key                      | 描述             |
+| ------------------------ | ---------------  |
+| server-handle-request    | EdenX Server 处理请求单次耗时                                                           |
+| ssr-render-shell         | [SSR]在使用 Streaming SSR 时， React 将渲染一个套壳(shell)优先传输。这里表明套壳渲染完成时间                              |
+| ssr-render-html          | [SSR] React 将组件树渲染成 html 所消耗的时间，通常不会超过 50ms                                                         |
+| server-middleware        | EdenX 自定义 Server `Middleware` 执行总时                                                                           |
+| server-loader            | Server 端整体 Data Loader 耗时                                                                                     |
+| server-loader-#id        | Server 端各个 Data Loader 耗时                                                                                      |
+| server-loader-navigation | 前端导航时，服务端 Data Loader 的整体耗时                                                                              |
+
+Modenr.js 服务端流程如图所示：
+
+![server](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/edenx-website/e374def0-c179-40aa-9cfe-e82e181663b1.jpeg)
+
+
+## 内置 Monitor
+
+import InternalMetrics from '@site-docs/components/internal-metrics.mdx';
+
+<InternalMetrics />
+
+## Server-Timing
+
+在 Modern.js 中，服务端还会额外将各阶段指标作为 Server-Timing 注入到 HTML 响应头中。
+
+在浏览器中，开发者可以通过 [Performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance) 获取：
+
+```ts
+const navigation = performance.getEntriesByType('navigation')[0];
+const serverTiming = navigation.serverTiming;
+console.log(serverTiming);
+```

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

@@ -0,0 +1,157 @@
+# 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，但只能在[服务端中间件](/apis/app/runtime/web-server/unstable_middleware)或服务端插件中注册，在 Data Loader、组件、init 函数中无法注册。
+
+:::note
+目前暂未开放服务端插件，后续会补充相关文档。
+:::
+
+```ts title="server/index.ts"
+import type { CoreMonitors } from '@modern-js/types';
+const injectMonitorMiddleware = (c) => {
+    const monitors = c.get('monitors');
+    const myMonitor = (event: MonitorEvent) => {
+        if (event.type === 'log') {
+          // some code
+        } else {
+          // some other code
+        }
+    }
+    monitors.push(myMonitor);
+    return next();
+}
+
+export const middlewares = [injectMonitorMiddleware]
+```
+
+## 调用 Monitors
+
+Modern.js 允许开发者在 Data Loader、组件中调用 Monitors。
+
+:::tip
+只有在 Node.js 环境才可以调用 Monitors，在浏览器环境调用无任何效果。
+:::
+
+在 Data Loader 中，开发者可以这样使用：
+
+```ts title="routes/page.data.ts"
+import { 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 { getMonitors } from '@modern-js/runtime';
+const Page = () => {
+    const { context } = useRuntimeContext();
+    if (process.env.MODERN_TARGET === 'node') {
+        const monitors = getMonitors();
+        monitors.info();
+    }
+    return <div>Hello World</div>
+}
+export default Page;
+```
+
+在中间件中，我们也可以调用 Monitors，但方式与在运行时代码中不同，需要通过 `context` 来获取：
+
+```ts title="server/index.ts"
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+const time: UnstableMiddleware = async (c, next) => {
+  const start = Date.now();
+  await next();
+  const end = Date.now();
+  const monitors = c.get('monitors');
+  monitors.info(`${end - start}`);
+};
+
+export const unstableMiddleware: UnstableMiddleware[] = [time];
+```
+
+

package/docs/zh/guides/basic-features/data/_meta.json

@@ -1 +1 @@
-["data-fetch", "data-write"]
+["data-fetch", "data-write", "data-cache"]

package/docs/zh/guides/basic-features/data/data-cache.mdx

@@ -0,0 +1,162 @@
+---
+title: 数据缓存
+sidebar_position: 4
+---
+# 数据缓存
+
+`cache` 函数可以让你缓存数据获取或计算的结果。
+
+## 基本用法
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser(user); // 函数入参发生变化时，函数会重新执行
+  return {
+    user,
+  };
+};
+```
+
+### 参数
+
+- `fn`: 需要缓存的数据获取或计算的函数
+- `options`（可选）: 缓存配置
+  - `tag`: 用于标识缓存的标签，可以基于这个标签使缓存失效
+  - `maxAge`: 缓存的有效期 (毫秒)
+  - `revalidate`: 重新验证缓存的时间窗口（毫秒），与 HTTP Cache-Control 的 stale-while-revalidate 功能一致
+
+`options` 参数的类型如下：
+
+```ts
+interface CacheOptions {
+  tag?: string | string[];
+  maxAge?: number;
+  revalidate?: number;
+}
+```
+
+### 返回值
+
+`cache` 函数会返回一个新的函数，该函数有缓存的能力，多次调用该函数，不会重复执行 `fn` 函数。
+
+## 使用范围
+
+与 react 的 [cache](https://react.dev/reference/react/cache) 函数只能在 server component 组件中使用不同，
+EdenX 提供的 `cache` 函数可以在任意的前端或服务端的代码中使用。
+
+## 详细用法
+
+### 无 `options` 参数
+
+当无 `options` 参数传入时，主要可以用于 SSR 项目，缓存的生命周期是单次 ssr 渲染的请求，如可以在多个 data loader 中调用同一个 cachedFn 时，不会重复执行 cachedFn 函数。这样可以在不同的 data loader 中共享数据，同时避免重复的请求，EdenX 会在每次收到服务端请求时，重新执行 `fn` 函数。
+
+:::info
+无 `options` 参数时，可以看作是 react [`cache`](https://react.dev/reference/react/cache) 函数的替代品，可以在任意服务端代码中使用（比如可以在 SSR 项目的 data loader 中），不局限于 server component。
+:::
+
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser();
+  return {
+    user,
+  };
+};
+```
+
+### 有 `options` 参数
+
+#### `maxAge` 参数
+
+每次计算完成后，框架会记录写入缓存的时间，当再次调用该函数时，会根据 `maxAge` 参数判断缓存是否过期，如果过期，则重新执行 `fn` 函数，否则返回缓存的数据。
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,  // 在 2 分钟内调用该函数会返回缓存的数据
+  }
+);
+```
+
+#### `revalidate` 参数
+
+`revalidate` 参数用于设置缓存过期后，重新验证缓存的时间窗口，可以和 `maxAge` 参数一起使用，类似与 HTTP Cache-Control 的 stale-while-revalidate 模式。
+
+
+如以下示例，在缓存未过期的 2分钟内，如果调用 `getDashboardStats` 函数，会返回缓存的数据，如果缓存过期，2分到3分钟内，收到的请求会先返回旧数据，然后后台会重新请求数据，并更新缓存。
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,
+    revalidate: CacheTime.MINUTE * 1,
+  }
+);
+```
+
+#### `tag` 参数
+
+`tag` 参数用于标识缓存的标签，可以传入一个字符串或字符串数组，可以基于这个标签使缓存失效，多个缓存函数可以使用一个标签。
+
+```ts
+import { cache, revalidateTag } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchDashboardStats();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+const getComplexStatistics = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
+```
+
+
+### 存储
+
+目前不管是客户端还是服务端，缓存都存储在内存中，默认情况下所有缓存函数共享的存储上限是 1GB，当达到存储上限后，使用 LRU 算法移除旧的缓存。
+
+:::info
+考虑到 `cache` 函数缓存的结果内容不会很大，所以目前默认都存储在内存中
+:::
+
+可以通过 `configureCache` 函数指定缓存的存储上限：
+
+```ts
+import { configureCache, CacheSize } from '@modern-js/runtime/cache';
+
+configureCache({
+  maxSize: CacheSize.MB * 10, // 10MB
+});
+```

package/i18n.json

@@ -79,6 +79,10 @@
     "zh": "优化页面性能",
     "en": "Optimize Page Performance"
   },
+  "server-monitor": {
+    "zh": "服务端监控",
+    "en": "Server Monitor"
+  },
   "micro-frontend": {
     "zh": "微前端",
     "en": "Micro Frontend"

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.65.1",
+  "version": "2.65.3",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.65.1"
+    "@modern-js/sandpack-react": "2.65.3"
   },
   "devDependencies": {
-    "@rspress/shared": "1.40.2",
+    "@rspress/shared": "1.42.0",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^16",
     "classnames": "^2",
@@ -33,7 +33,7 @@
     "fs-extra": "^10",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "rspress": "1.41.0",
+    "rspress": "1.42.0",
     "ts-node": "^10.9.1",
     "typescript": "^5"
   },