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

package/docs/zh/guides/basic-features/render/streaming-ssr.mdx

@@ -0,0 +1,276 @@
+---
+title: 服务端流式渲染（Streaming SSR）
+---
+
+# 流式服务端渲染（Streaming SSR）
+
+流式渲染是一种先进的渲染方式，它可以在页面渲染过程中逐步返回内容，从而显著提升用户体验。
+
+在传统的 SSR 渲染方式中，页面的渲染是一次性完成的，需要等待所有数据加载完成后才能返回完整的 HTML。而在流式渲染中，页面的渲染是逐步完成的，可以边渲染边返回，用户能够更快地看到初始内容。
+
+:::info 默认模式
+**Streaming SSR 是 Modern.js SSR 的默认渲染模式**。当你启用 SSR 时，无需额外配置即可使用流式渲染。
+
+如果你需要切换到传统的 SSR 模式（等待所有数据加载完成后一次性返回），可以配置 `server.ssr.mode` 为 `'string'`。详细说明请参考[服务端渲染（SSR）](/guides/basic-features/render/ssr)文档。
+:::
+
+相比传统 SSR 渲染：
+
+- **更快感知速度**：流式渲染可以在渲染过程中逐步显示内容，能够以最快的速度显示业务首页
+- **更好的用户体验**：通过流式渲染，用户可以更快地看到页面上的内容，而不需要等待整个页面都渲染完成后才能交互
+- **更好的性能控制**：流式渲染可以让开发者更好地控制页面加载的优先级和顺序，从而更好地优化性能和用户体验
+- **更好的适应性**：流式渲染可以更好地适应不同网络速度和设备性能，使得页面在各种环境下都能有更好的表现
+
+## 开启流式渲染
+
+Modern.js 支持了 React 18+ 的流式渲染。当你启用 SSR 时，流式渲染默认开启：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true, // 默认启用流式渲染
+  },
+});
+```
+
+如果你需要显式指定流式渲染模式，可以配置：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream', // 显式指定流式渲染模式
+    },
+  },
+});
+```
+
+Modern.js 的流式渲染基于 React Router 实现，主要涉及 API 有：
+
+- [`Await`](https://reactrouter.com/en/main/components/await)：用于渲染 Data Loader 返回的异步数据。
+- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value)：用于从最近的父级 `Await` 组件中获取数据。
+
+## 获取数据
+
+```ts title="user/[id]/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` 必须接收一个对象类型的参数，不能直接传递 Promise 对象。
+
+另外，`defer` 还可以同时接收异步数据和同步数据。在下述例子中，我们等待部分耗时较短的请求，在响应后通过对象数据返回，而耗时较长时间的请求，则通过 Promise 返回：
+
+```ts title="user/[id]/page.data.ts"
+export const loader = async ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 2000);
+  });
+
+  const otherData = new Promise<string>(resolve => {
+    setTimeout(() => {
+      resolve('some sync data');
+    }, 200);
+  });
+
+  return defer({
+    data: user,
+    other: await otherData,
+  });
+};
+```
+
+这样，应用无需等待最耗时的数据请求响应后才展示页面内容，可以优先展示部分有数据的页面内容
+
+## 渲染数据
+
+通过 `Await` 组件，可以获取到 Data Loader 中异步返回的数据，然后进行渲染。例如：
+
+```tsx title="user/[id]/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 注意
+从 `page.data.ts` 文件导入类型时，需要使用 `import type` 语法，保证只导入类型信息，避免 Data Loader 的代码打包到前端产物中。
+:::
+
+在组件中，你也可以通过 `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>;
+}
+```
+
+## 控制是否等待全部内容再输出
+
+流式传输可以提高用户体验，因为当页面内容可用时，用户可以及时感知到它们。但在部分场景下（例如 SEO 爬虫、特定 AB 实验或合规页面）希望等所有内容完成后再一次性输出。
+
+Modern.js 默认行为的判定优先级为：
+
+Modern.js 使用 [isbot](https://www.npmjs.com/package/isbot) 对请求的 `user-agent`，以判断请求是否来自爬虫。
+
+1. 请求头 `x-should-stream-all`（中间件可写）。
+2. 环境变量 `MODERN_JS_STREAM_TO_STRING`（强制全量）。
+3. [isbot](https://www.npmjs.com/package/isbot) 检测 `user-agent`（爬虫全量）。
+4. 默认流式（先 shell 后内容）。
+
+你可以在自定义中间件里按请求动态写入标记，控制是否等待全部内容：
+
+```ts title="middleware 示例"
+export const middleware = async (ctx, next) => {
+  const ua = ctx.req.header('user-agent') || '';
+  const shouldWaitAll =
+    /Lighthouse|Googlebot/i.test(ua) || ctx.req.path === '/marketing';
+
+  // 写入布尔值字符串，true 表示使用 onAllReady，false 表示使用 onShellReady
+  ctx.req.headers.set('x-should-stream-all', String(shouldWaitAll));
+
+  await next();
+};
+```
+
+import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
+
+<StreamSSRPerformance />
+
+## 相关文档
+
+- [渲染模式总览](/guides/basic-features/render/overview)
+- [服务端渲染（SSR）](/guides/basic-features/render/ssr)
+- [渲染缓存](/guides/basic-features/render/ssr-cache)
+- [React Server Components（RSC）](/guides/basic-features/render/rsc) - 与 Streaming SSR 结合使用
+- [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37) - React 18 架构说明

package/docs/zh/guides/basic-features/render/tanstack-rsc.mdx

@@ -0,0 +1,226 @@
+---
+title: TanStack Router RSC
+---
+
+# TanStack Router RSC
+
+Modern.js 支持在 TanStack Router 项目中使用 React Server Components（RSC）。这套集成会将 RSC 输出作为路由数据处理：Loader 返回序列化后的 Flight stream，由 TanStack Router 管理数据生命周期，Modern.js 负责提供 Flight 渲染、解码与序列化适配器。
+
+这套集成遵循 TanStack Router 的数据模型，不会使用 React Router 的 RSC 渲染器或 `RSCStaticRouter`。
+
+## 适用场景
+
+当你希望实现以下能力时，可以使用 TanStack Router RSC：
+
+- 在服务端渲染数据密集型 UI，同时继续由 TanStack Router 管理路由与缓存。
+- 从路由 Loader 返回服务端渲染的 UI，并通过 `Route.useLoaderData()` 消费。
+- 将交互 UI 保留在 Client Component 中，将复杂的数据访问、格式化与标记生成放在服务端。
+- 在数据写入后，通过 TanStack Router 的 invalidation 刷新服务端渲染的 UI。
+
+如果路由组件本身可以直接作为普通 Server Component 使用，请先阅读通用的 [React Server Components（RSC）](/guides/basic-features/render/rsc) 文档。当服务端 UI 需要通过 TanStack Router Loader 数据传递时，再使用本文介绍的能力。
+
+## 前置条件
+
+使用 TanStack Router RSC 前，请确保项目满足以下条件：
+
+1. React 与 React DOM 已升级到 19 或更高版本。
+2. 通过 [`server.rsc`](/configure/app/server/rsc) 开启 RSC。
+3. 已选择 TanStack Router 作为 Modern.js 路由运行时。
+4. 已完成 [React Server Components（RSC）](/guides/basic-features/render/rsc) 中的基础配置，包括必要的 RSC 运行时依赖。
+
+:::tip
+如果项目通过 `--router tanstack` 创建，请在路由代码中使用 `@modern-js/plugin-tanstack/runtime`，这样可以让路由代码与生成它的 TanStack 插件保持一致。
+:::
+
+## 开启 RSC
+
+设置 `server.rsc` 为 `true`，并开启 TanStack Router 运行时：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+  },
+  server: {
+    rsc: true,
+  },
+});
+```
+
+## 导入路径
+
+在应用代码中使用 TanStack 插件的运行时导出：
+
+- 运行时 API：`@modern-js/plugin-tanstack/runtime`
+- 仅服务端 RSC 辅助函数：`@modern-js/plugin-tanstack/runtime/rsc/server`
+- 客户端 RSC 辅助函数：`@modern-js/plugin-tanstack/runtime/rsc/client`
+
+下面的示例都使用这些路径。
+
+## Payload Router 行为
+
+开启 `server.rsc` 后，TanStack RSC 导航会使用原生的 payload-router 路径，而不是 React Router 的 `RSCStaticRouter` 路径：
+
+- 需要服务端 Loader 数据的浏览器导航会携带 `x-rsc-tree: true` 请求当前 URL。
+- 服务端会执行匹配到的 TanStack 路由 Loader，并序列化包含匹配路由 id、params、loader data、errors、location 与路由元信息的 `ServerPayload`，再通过 Modern.js RSC renderer 以流式方式返回。
+- Loader 重定向会以 `X-Modernjs-Redirect` 与 `X-Modernjs-BaseUrl` 响应头返回，让客户端继续交给 TanStack Router 完成导航。
+- `404` 响应和 TanStack `notFound()` 结果会作为路由错误保留，从而渲染最近的 TanStack not-found boundary。
+- 标记了 client loader 的路由会在 RSC 导航期间继续执行自己的 client loader。对应的服务端 loader data 会从 RSC payload 中有意省略，避免用服务端数据覆盖 client-loader 结果。
+
+首次 SSR hydration 仍然使用 TanStack Router 现有的 SSR bootstrap scripts。payload-router 请求路径只用于后续 RSC 导航和 invalidation，因此同一套路由树可以同时使用普通 TanStack SSR loader data 与 RSC loader data。
+
+## 从 Loader 渲染服务端 UI
+
+当服务端输出不需要客户端提供插槽时，使用 `renderServerComponent`。Loader 在服务端执行，将 Server Component 渲染成 Flight stream，并返回可以被客户端路由组件渲染的值。
+
+```tsx title="src/routes/products/page.data.tsx"
+import { renderServerComponent } from '@modern-js/plugin-tanstack/runtime/rsc/server';
+import { ProductGrid } from './ProductGrid';
+
+export async function loader() {
+  const products = await fetchProducts();
+
+  return {
+    ProductGrid: await renderServerComponent(
+      <ProductGrid products={products} />,
+    ),
+  };
+}
+```
+
+```tsx title="src/routes/products/page.tsx"
+import { createFileRoute } from '@modern-js/plugin-tanstack/runtime';
+
+export const Route = createFileRoute('/products')({
+  component: ProductsPage,
+});
+
+function ProductsPage() {
+  const { ProductGrid } = Route.useLoaderData();
+
+  return <main>{ProductGrid}</main>;
+}
+```
+
+:::warning
+当客户端路由会消费 Loader 返回值时，不要从 TanStack Router Loader 直接返回原始 JSX。请使用 `renderServerComponent` 或 `createCompositeComponent` 包装服务端渲染的 UI，使其能够通过 TanStack Router 的 SSR 数据管线序列化。
+:::
+
+## 渲染带客户端插槽的服务端 UI
+
+当服务端渲染的标记需要接收客户端内容、render props 或交互组件时，使用 `createCompositeComponent`。服务端组件会接收插槽占位符，客户端路由通过 `<CompositeComponent>` 提供插槽实现。
+
+```tsx title="src/routes/products/page.data.tsx"
+import { createCompositeComponent } from '@modern-js/plugin-tanstack/runtime/rsc/server';
+import type React from 'react';
+
+export async function loader() {
+  return {
+    ProductCard: await createCompositeComponent<{
+      AddToCart?: (id: string) => React.ReactNode;
+      children?: React.ReactNode;
+    }>(async props => {
+      const product = await fetchFeaturedProduct();
+
+      return (
+        <article>
+          <h2>{product.name}</h2>
+          {props.children}
+          {props.AddToCart?.(product.id)}
+        </article>
+      );
+    }),
+  };
+}
+```
+
+```tsx title="src/routes/products/page.tsx"
+import {
+  CompositeComponent,
+  createFileRoute,
+} from '@modern-js/plugin-tanstack/runtime';
+import { AddToCartButton } from '../../components/AddToCartButton';
+
+export const Route = createFileRoute('/products')({
+  component: ProductsPage,
+});
+
+function ProductsPage() {
+  const { ProductCard } = Route.useLoaderData();
+
+  return (
+    <CompositeComponent
+      src={ProductCard}
+      AddToCart={id => <AddToCartButton productId={id} />}
+    >
+      <p>Ships today.</p>
+    </CompositeComponent>
+  );
+}
+```
+
+如果希望缺失的插槽实现在开发阶段尽早报错，可以使用 `strict`：
+
+```tsx
+<CompositeComponent src={ProductCard} strict />
+```
+
+## 刷新 RSC 数据
+
+由于 RSC 值属于 TanStack Router 数据，应通过 TanStack Router invalidation 刷新：
+
+```tsx
+import { useRouter } from '@modern-js/plugin-tanstack/runtime';
+
+function SaveButton() {
+  const router = useRouter();
+
+  return (
+    <button
+      onClick={async () => {
+        await saveProduct();
+        await router.invalidate();
+      }}
+    >
+      Save
+    </button>
+  );
+}
+```
+
+如果将 RSC 值存入 TanStack Query，请为对应 query 关闭 structural sharing。RSC 值是 Flight stream 外层的代理对象，对其进行深度结构比较没有实际意义。
+
+## 注意事项
+
+- `*/rsc/server` 中的服务端辅助函数只能被 Loader 或服务端模块导入。
+- 客户端路由可以将 `renderServerComponent` 的返回值直接作为 React node 渲染。
+- `<CompositeComponent>` 只应接收 `createCompositeComponent` 返回的值。
+- 插槽函数应返回 React node，并只接收可序列化参数。不可序列化对象、请求对象、数据库句柄等应保留在服务端代码中。
+- TanStack Router invalidation 是刷新边界。除非应用有明确的缓存策略，否则不要在 Router 之外再构建一套并行的 RSC 缓存。
+
+## 最佳实践
+
+### 优先由 Router 管理数据
+
+将 RSC 值保存在 Loader 数据中，并让 TanStack Router 管理缓存、水合、失效与导航。这样可以保持实现与 TanStack Router 对齐，避免引入并行的 RSC 路由层。
+
+### 使用能满足需求的最小辅助函数
+
+没有客户端插槽的 UI 使用 `renderServerComponent`。只有当服务端渲染的标记需要客户端插槽或 render props 时，才使用 `createCompositeComponent`。
+
+### 保持服务端与客户端边界清晰
+
+不要在客户端组件中导入服务端辅助函数。`CompositeComponent` 应从运行时导出或 `*/rsc/client` 导入；`renderServerComponent` 与 `createCompositeComponent` 只应从 `*/rsc/server` 导入。
+
+### 自动化修改
+
+使用 coding agent 或 codemod 修改相关代码时，应将 TanStack RSC 的改动限制在 TanStack Router 插件及其 RSC 辅助导出内。不要为了该能力修改 Modern.js 核心路由，也不要替换 TanStack Router 的 SSR 管线。
+
+## 相关链接
+
+- [React Server Components（RSC）](/guides/basic-features/render/rsc)
+- [路由基础](/guides/basic-features/routes/routes)
+- [数据缓存](/guides/basic-features/data/data-cache)
+- [TanStack Router 文档](https://tanstack.com/router)

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

@@ -0,0 +1 @@
+["routes", "config-routes"]