@modern-js/main-doc 2.42.2 → 2.43.0

package/docs/zh/guides/advanced-features/ssr/cache.mdx

@@ -0,0 +1,189 @@
+---
+sidebar_position: 3
+title: 缓存
+---
+
+# 渲染缓存
+
+有时我们会将计算结果进行缓存，例如 React useMemo, useCallback Hook。
+通过缓存我们可以减少计算的次数来减少 CPU 资源占用，提高用户体验。
+
+通过将服务器端渲染（SSR）结果进行缓存能够减少服务器每次请求时的计算和渲染时间，从而加速页面加载速度，提高用户体验。
+降低服务端负载，节省计算资源，提高用户访问速度。
+
+:::info
+需要 x.43.0+
+:::
+
+## 配置方式
+
+在 `server/cache.[t|j]s` 中配置缓存即可开启缓存：
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/runtime/server';
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```
+
+## 配置说明
+
+### 缓存配置
+
+缓存策略参考 [stale-while-revalidate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) 进行实现。
+
+在 `maxAge` 时间内会直接返回缓存内容，超过 `maxAge` 但在 `staleWhileRevalidate` 内也会直接返回缓存内容，但同时会异步做一次重新渲染。
+
+**Object 类型**
+
+```ts
+export interface CacheControl {
+  maxAge: number;
+
+  staleWhileRevalidate: number;
+
+  customKey?: string | ((pathname: string) => string);
+}
+```
+
+其中 customKey 为自定义缓存 key。默认情况下 Modern.js 将会把请求 pathname 作为 key 进行缓存，但在某些情况下这不能满足你的需求，开发者可以进行自定义。
+
+**Function 类型**
+
+```ts
+export type CacheOptionProvider = (
+  req: IncomingMessage,
+) => Promise<CacheControl> | CacheControl;
+```
+
+有时开发者需要通过 req 来自定义缓存 key，可以配置为函数的形式进行处理, 例如以下代码：
+
+```ts title="server/cache.ts"
+
+import type { CacheOption, CacheOptionProvider } from '@modern-js/runtime/server';
+
+const provider: CacheOptionProvider = (req) => {
+  const { url, headers, ... } = req;
+
+  const key = computedKey(url, headers, ...);
+
+  return {
+    maxAge: 500, // ms
+    staleWhileRevalidate: 1000, // ms
+    customKey: key,
+  }
+}
+
+export const cacheOption: CacheOption = provider;
+```
+
+**Mapping 类型**
+
+```ts
+export type CacheOptions = Record<string, CacheControl | CacheOptionProvider>;
+```
+
+有时开发者面对不同的路由需要应用不同的缓存策略。我们也提供一种映射的方式进行配置, 以下列代码为例子
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/runtime/server';
+
+export const cacheOption: CacheOption = {
+  '/home': {
+    maxAge: 50,
+    staleWhileRevalidate: 100,
+  },
+  '/about': {
+    maxAge: 1000 * 60 * 60 * 24, // one day
+    staleWhileRevalidate: 1000 * 60 * 60 * 24 * 2 // two day
+  },
+  '*': (req) => { // 若上述路由无法匹配，则会匹配到 '*'
+    const { url, headers, ... } = req;
+    const key = computedKey(url, headers, ...);
+
+    return {
+      maxAge: 500,
+      staleWhileRevalidate: 1000,
+      customKey: key,
+    }
+  }
+}
+```
+
+- 路由 `http://xxx/home` 将会应用第一条规则。
+- 路由 `http://xxx/about` 将会应用第二条规则。
+- 路由 `http://xxx/abc` 将会应用最后一条规则。
+
+上述 `/home` 和 `/about` 将会作为模式进行匹配，这意味着 `/home/abc` 也会匹配上该规则。
+同时，你也可以在其中编写正则语法：`/home/.+`
+
+### 缓存容器
+
+默认情况下，Server 将会使用内存进行缓存。但通常情况下服务将会部署在 serverless 上。每一次的服务访问可能都是一个新的进程，这样每次访问都不能应用缓存
+
+故开发者也可以自定义缓存容器，容器需实现接口 `Containter`
+
+```ts
+export interface Containter<K = string, V = string> {
+  /**
+   * Returns a specified element from the containter. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Containter.
+   * @returns Returns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.
+   */
+  get: (key: K) => Promise<V | undefined>;
+
+  /**
+   * Adds a new element with a specified key and value to the containter. If an element with the same key already exists, the element will be updated.
+   *
+   * The ttl indicates cache expiration time.
+   */
+  set: (key: K, value: V, options?: { ttl?: number }) => Promise<this>;
+
+  /**
+   * @returns boolean indicating whether an element with the specified key exists or not.
+   */
+  has: (key: K) => Promise<boolean>;
+
+  /**
+   * @returns true if an element in the containter existed and has been removed, or false if the element does not exist.
+   */
+  delete: (key: K) => Promise<boolean>;
+}
+```
+
+以下面代码为例，开发者可实现一个 redis 容器。
+
+```ts
+import type { Containter, CacheOption } from '@modern-js/runtime/server';
+
+class RedisContainter implements Containter {
+  redis = new Redis();
+
+  async get(key: string) {
+    return this.redis.get(key);
+  }
+
+  async set(key: string, value: string): Promise<this> {
+    this.redis.set(key, value);
+    return this;
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.redis.has(key);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.redis.delete(key);
+  }
+}
+
+const containter = new RedisContainter();
+
+export const customContainer: Containter = containter;
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```

package/docs/zh/guides/advanced-features/ssr/index.mdx

@@ -0,0 +1,22 @@
+# 服务端渲染
+
+通过在服务器端将网页的 HTML 内容渲染成完整的网页，然后将生成的网页发送到客户端，客户端只需要显示网页即可，不需要再进行额外的渲染。
+
+它主要的优势在于
+
+- 提高首屏加载速度：SSR 可以在服务器端生成完整的网页，客户端只需要下载网页内容即可，不需要再进行额外的渲染，从而提高了首屏加载速度。
+- 提高用户体验：SSR 可以提高网页的响应速度，从而提高用户体验。
+- 有利于 SEO：SSR 可以生成完整的 HTML 内容，搜索引擎可以直接索引 HTML 内容，从而提高网站的排名。
+
+如果你有以下场景的需求，开发者可以考虑使用 SSR 来渲染你的页面：
+
+1. 对首屏加载速度要求较高的网站，如电商网站、新闻网站等。
+2. 对用户体验要求较高的网站，如社交网站、游戏网站等。
+3. 对 SEO 要求较高的网站，如企业官网、博客等。
+
+在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。
+除了开箱即用的 SSR 服务，为了保证开发者的开发体验，我们还具备：
+
+- 完备的 SSR 降级策略，保证页面能够安全运行。
+- 自动分割子路由，按需加载，减少首屏资源体积。
+- 内置缓存系统，解决服务端负载高的问题。

package/docs/zh/guides/advanced-features/ssr/stream.mdx

@@ -0,0 +1,240 @@
+---
+sidebar_position: 2
+title: 流式渲染
+---
+
+# 流式渲染
+
+## 概述
+
+流式渲染是一种新的渲染方式，它可以在用户与页面交互时，实时地更新页面内容，从而提高用户体验。
+
+在传统的渲染方式中，页面的渲染是一次性完成的，而在流式渲染中，页面的渲染是逐步完成的，在用户与页面交互时，逐步加载数据，而不是一次性加载所有数据。
+
+相比传统渲染：
+
+- 拥有更快感知速度：流式渲染可以在渲染过程中逐步显示内容能够以最快的速度显示业务首页。
+- 拥有更好的用户体验：通过流式渲染，用户可以更快地看到页面上的内容，而不需要等待整个页面都渲染完成后才能交互。
+- 拥有更好的性能控制：流式渲染可以让开发者更好地控制页面加载的优先级和顺序，从而更好地优化性能和用户体验。
+- 更好的适应性：流式渲染可以更好地适应不同网络速度和设备性能，使得页面在各种环境下都能有更好的表现。
+
+## 使用
+
+Modern.js 支持了 React 18 的流式渲染，可以通过如下配置启用：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream',
+    },
+  },
+});
+```
+
+Modern.js 的流式渲染基于 React Router 实现，主要涉及 API 有：
+
+- [`defer`](https://reactrouter.com/en/main/utils/defer)：在 Data Loader 中使用，用于支持异步获取数据。
+- [`Await`](https://reactrouter.com/en/main/components/await)：用于渲染 Data Loader 返回的异步数据。
+- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value)：用于从最近的父级 `Await` 组件中获取数据。
+
+### 异步获取数据
+
+```ts title="page.data.ts"
+import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+interface User {
+  name: string;
+  age: number;
+}
+
+export interface Data {
+  data: User;
+}
+
+export const loader = ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 200);
+  });
+
+  return defer({ data: user });
+};
+```
+
+`user` 是一个 Promise 类型的对象，表示需要异步获取的数据，通过 `defer` 处理需要异步获取的 `user`。注意，`defer` 必须接收一个对象类型的参数，
+因此， 传入 `defer` 的参数为：`{ data: user }`
+
+`defer` 还可以同时接收异步数据和同步数据。例如：
+
+```ts title="page.data.ts"
+// 省略部分代码
+
+export const loader = ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 200);
+  });
+
+  const otherData = new Promise<string>(resolve => {
+    setTimeout(() => {
+      resolve('some sync data');
+    }, 200);
+  });
+
+  return defer({
+    data: user,
+    other: await otherData,
+  });
+};
+```
+
+`otherData` 前加了 `await`，所以是同步获取的数据，它可以和异步获取的数据 `user` 同时传入 `defer`。
+
+### 渲染异步数据
+
+通过 `Await` 组件，可以获取到 Data Loader 中异步返回的数据，然后进行渲染。例如：
+
+```tsx title="page.tsx"
+import { Await, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+import type { Data } from './page.data';
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          {user => {
+            return (
+              <div id="data">
+                name: {user.name}, age: {user.age}
+              </div>
+            );
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
+
+export default Page;
+```
+
+`Await` 需要包裹在 `Suspense` 组件内部，`Await` 的 `resolve` 传入的是 Data Loader 异步获取的数据，当数据获取完成后，
+通过 [Render Props](https://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) 模式，渲染获取到的数据。在数据的获取阶段，将展示
+`Suspense` 组件 `fallback` 属性设置的内容。
+
+:::warning 注意
+从 Data Loader 文件导入类型时，需要使用 import type 语法，保证只导入类型信息，这样可以避免 Data Loader 的代码打包到前端产物的 bundle 文件中。
+
+所以，这里的导入方式为：`import type { Data } from './page.data'`;
+
+:::
+
+也可以通过 `useAsyncValue` 获取 Data Loader 返回的异步数据。例如：
+
+```tsx title='page.tsx'
+import { useAsyncValue } from '@modern-js/runtime/router';
+
+// 省略部分代码
+
+const UserInfo = () => {
+  const user = useAsyncValue();
+
+  return (
+    <div>
+      name: {user.name}, age: {user.age}
+    </div>
+  );
+};
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          <UserInfo />
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
+
+export default Page;
+```
+
+### 错误处理
+
+`Await` 组件的 `errorElement` 属性，可以用来处理当 Data Loader 执行时，或者子组件渲染时抛出的错误。
+例如，我们故意在 Data Loader 函数中抛出错误：
+
+```ts title="page.loader.ts"
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const data = new Promise((resolve, reject) => {
+    setTimeout(() => {
+      reject(new Error('error occurs'));
+    }, 200);
+  });
+
+  return defer({ data });
+};
+```
+
+然后通过 `useAsyncError` 获取错误，并将用于渲染错误信息的组件赋值给 `Await` 组件的 `errorElement` 属性：
+
+```tsx title="page.ts"
+import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+
+export default function Page() {
+  const data = useLoaderData();
+
+  return (
+    <div>
+      Error page
+      <Suspense fallback={<div>loading ...</div>}>
+        <Await resolve={data.data} errorElement={<ErrorElement />}>
+          {(data: any) => {
+            return <div>never displayed</div>;
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+}
+
+function ErrorElement() {
+  const error = useAsyncError() as Error;
+  return <p>Something went wrong! {error.message}</p>;
+}
+```
+
+:::info 补充信息
+
+1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
+2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
+
+:::

package/docs/zh/guides/advanced-features/{ssr.mdx → ssr/usage.mdx}

@@ -1,10 +1,9 @@
 ---
-sidebar_position: 4
+sidebar_position: 1
+title: 基础使用
 ---
 
-# 服务端渲染
-
-在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
+# 基础使用
 
 启用 SSR 非常简单，只需要设置 [`server.ssr`](/configure/app/server/ssr) 为 `true` 即可：
 
@@ -139,6 +138,10 @@ CSR 中这类问题不易被发觉，因此从 CSR 切换到 SSR 时，如果不
 
 ## Serverless Pre-render
 
+:::warning
+x.43.0+ 已废弃，请使用 [SSR Cache](guides/advanced-features/ssr/cache) 替代
+:::
+
 Modern.js 提供 Serverless Pre-rendering (SPR) 这一特性来提升 SSR 性能。
 
 SPR 利用预渲染与缓存技术，为 SSR 页面提供静态 Web 的响应性能。它让 SSR 应用拥有静态 Web 页面的响应速度与稳定性，同时还能保持数据的动态更新。
@@ -324,224 +327,3 @@ export const loader = () => {
 需要注意的是，此时获取到的是 HTML 请求的请求头，不一定适用于接口请求，因此**千万不能**透传所有请求头。并且，一些后端接口，或是通用网关，会根据请求头中的信息做校验，全量透传容易出现各种难以排查的问题，推荐**按需透传**。
 
 如果实在需要透传所有请求头，请务必过滤 `host` 字段。
-
-## 流式渲染
-
-Modern.js 支持了 React 18 的流式渲染，可以通过如下配置启用：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  server: {
-    ssr: {
-      mode: 'stream',
-    },
-  },
-});
-```
-
-Modern.js 的流式渲染基于 React Router 实现，主要涉及 API 有：
-
-- [`defer`](https://reactrouter.com/en/main/utils/defer)：在 Data Loader 中使用，用于支持异步获取数据。
-- [`Await`](https://reactrouter.com/en/main/components/await)：用于渲染 Data Loader 返回的异步数据。
-- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value)：用于从最近的父级 `Await` 组件中获取数据。
-
-### 异步获取数据
-
-```ts title="page.data.ts"
-import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
-
-interface User {
-  name: string;
-  age: number;
-}
-
-export interface Data {
-  data: User;
-}
-
-export const loader = ({ params }: LoaderFunctionArgs) => {
-  const userId = params.id;
-
-  const user = new Promise<User>(resolve => {
-    setTimeout(() => {
-      resolve({
-        name: `user-${userId}`,
-        age: 18,
-      });
-    }, 200);
-  });
-
-  return defer({ data: user });
-};
-```
-
-`user` 是一个 Promise 类型的对象，表示需要异步获取的数据，通过 `defer` 处理需要异步获取的 `user`。注意，`defer` 必须接收一个对象类型的参数，
-因此， 传入 `defer` 的参数为：`{ data: user }`
-
-`defer` 还可以同时接收异步数据和同步数据。例如：
-
-```ts title="page.data.ts"
-// 省略部分代码
-
-export const loader = ({ params }: LoaderFunctionArgs) => {
-  const userId = params.id;
-
-  const user = new Promise<User>(resolve => {
-    setTimeout(() => {
-      resolve({
-        name: `user-${userId}`,
-        age: 18,
-      });
-    }, 200);
-  });
-
-  const otherData = new Promise<string>(resolve => {
-    setTimeout(() => {
-      resolve('some sync data');
-    }, 200);
-  });
-
-  return defer({
-    data: user,
-    other: await otherData,
-  });
-};
-```
-
-`otherData` 前加了 `await`，所以是同步获取的数据，它可以和异步获取的数据 `user` 同时传入 `defer`。
-
-### 渲染异步数据
-
-通过 `Await` 组件，可以获取到 Data Loader 中异步返回的数据，然后进行渲染。例如：
-
-```tsx title="page.tsx"
-import { Await, useLoaderData } from '@modern-js/runtime/router';
-import { Suspense } from 'react';
-import type { Data } from './page.data';
-
-const Page = () => {
-  const data = useLoaderData() as Data;
-
-  return (
-    <div>
-      User info:
-      <Suspense fallback={<div id="loading">loading user data ...</div>}>
-        <Await resolve={data.data}>
-          {user => {
-            return (
-              <div id="data">
-                name: {user.name}, age: {user.age}
-              </div>
-            );
-          }}
-        </Await>
-      </Suspense>
-    </div>
-  );
-};
-
-export default Page;
-```
-
-`Await` 需要包裹在 `Suspense` 组件内部，`Await` 的 `resolve` 传入的是 Data Loader 异步获取的数据，当数据获取完成后，
-通过 [Render Props](https://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) 模式，渲染获取到的数据。在数据的获取阶段，将展示
-`Suspense` 组件 `fallback` 属性设置的内容。
-
-:::warning 注意
-从 Data Loader 文件导入类型时，需要使用 import type 语法，保证只导入类型信息，这样可以避免 Data Loader 的代码打包到前端产物的 bundle 文件中。
-
-所以，这里的导入方式为：`import type { Data } from './page.data'`;
-
-:::
-
-也可以通过 `useAsyncValue` 获取 Data Loader 返回的异步数据。例如：
-
-```tsx title='page.tsx'
-import { useAsyncValue } from '@modern-js/runtime/router';
-
-// 省略部分代码
-
-const UserInfo = () => {
-  const user = useAsyncValue();
-
-  return (
-    <div>
-      name: {user.name}, age: {user.age}
-    </div>
-  );
-};
-
-const Page = () => {
-  const data = useLoaderData() as Data;
-
-  return (
-    <div>
-      User info:
-      <Suspense fallback={<div id="loading">loading user data ...</div>}>
-        <Await resolve={data.data}>
-          <UserInfo />
-        </Await>
-      </Suspense>
-    </div>
-  );
-};
-
-export default Page;
-```
-
-### 错误处理
-
-`Await` 组件的 `errorElement` 属性，可以用来处理当 Data Loader 执行时，或者子组件渲染时抛出的错误。
-例如，我们故意在 Data Loader 函数中抛出错误：
-
-```ts title="page.loader.ts"
-import { defer } from '@modern-js/runtime/router';
-
-export default () => {
-  const data = new Promise((resolve, reject) => {
-    setTimeout(() => {
-      reject(new Error('error occurs'));
-    }, 200);
-  });
-
-  return defer({ data });
-};
-```
-
-然后通过 `useAsyncError` 获取错误，并将用于渲染错误信息的组件赋值给 `Await` 组件的 `errorElement` 属性：
-
-```tsx title="page.ts"
-import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
-import { Suspense } from 'react';
-
-export default function Page() {
-  const data = useLoaderData();
-
-  return (
-    <div>
-      Error page
-      <Suspense fallback={<div>loading ...</div>}>
-        <Await resolve={data.data} errorElement={<ErrorElement />}>
-          {(data: any) => {
-            return <div>never displayed</div>;
-          }}
-        </Await>
-      </Suspense>
-    </div>
-  );
-}
-
-function ErrorElement() {
-  const error = useAsyncError() as Error;
-  return <p>Something went wrong! {error.message}</p>;
-}
-```
-
-:::info 补充信息
-
-1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
-2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
-
-:::