@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.99 → 3.4.0-ultramodern.1

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

@@ -1,226 +0,0 @@
----
-title: TanStack Router RSC
----
-
-# TanStack Router RSC
-
-Modern.js supports React Server Components (RSC) in TanStack Router projects by treating RSC output as router data. Loaders return serialized Flight streams, TanStack Router owns the data lifecycle, and Modern.js supplies the Flight renderer, decoder, and serialization adapter.
-
-This integration is designed for TanStack Router's data model. It does not use the React Router RSC renderer or `RSCStaticRouter`.
-
-## When to Use It
-
-Use TanStack Router RSC when you want to:
-
-- Render data-heavy UI on the server while keeping TanStack Router as the routing and cache owner.
-- Return server-rendered UI from route loaders and consume it with `Route.useLoaderData()`.
-- Keep interactive UI in Client Components while expensive data access, formatting, and markup generation stay on the server.
-- Refresh server-rendered UI with TanStack Router invalidation after mutations.
-
-For route components that can be ordinary Server Components, use the general [React Server Components (RSC)](/guides/basic-features/render/rsc) guide first. Use this page when server UI needs to flow through TanStack Router loader data.
-
-## Prerequisites
-
-Before using TanStack Router RSC, make sure the project has:
-
-1. React and React DOM 19 or later.
-2. RSC enabled with [`server.rsc`](/configure/app/server/rsc).
-3. TanStack Router selected as the Modern.js routing runtime.
-4. The base RSC setup from [React Server Components (RSC)](/guides/basic-features/render/rsc), including the required RSC runtime dependency.
-
-:::tip
-If your project was created with `--router tanstack`, use `@modern-js/plugin-tanstack/runtime` in route code. This keeps route code aligned with the TanStack plugin that generated it.
-:::
-
-## Enable RSC
-
-Set `server.rsc` to `true` and enable the TanStack Router runtime:
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-  },
-  server: {
-    rsc: true,
-  },
-});
-```
-
-## Import Paths
-
-Use the TanStack plugin runtime exports in application code:
-
-- Runtime APIs: `@modern-js/plugin-tanstack/runtime`
-- Server-only RSC helpers: `@modern-js/plugin-tanstack/runtime/rsc/server`
-- Client RSC helpers: `@modern-js/plugin-tanstack/runtime/rsc/client`
-
-The examples below use these paths.
-
-## Payload Router Behavior
-
-When `server.rsc` is enabled, TanStack RSC navigation uses a native payload-router path instead of the React Router `RSCStaticRouter` path:
-
-- Browser navigations that need server loader data request the current URL with `x-rsc-tree: true`.
-- The server runs the matched TanStack route loaders, serializes a `ServerPayload` with matched route ids, params, loader data, errors, location, and route metadata, then streams that payload through the Modern.js RSC renderer.
-- Loader redirects are returned with `X-Modernjs-Redirect` and `X-Modernjs-BaseUrl` headers so the client can continue the navigation through TanStack Router.
-- `404` responses and TanStack `notFound()` results are preserved as route errors so the nearest TanStack not-found boundary can render.
-- Routes marked with a client loader keep running their client loader during RSC navigation. Their server loader data is intentionally omitted from the RSC payload to avoid hydrating stale server data over the client-loader result.
-
-Initial SSR hydration still uses TanStack Router's existing SSR bootstrap scripts. The payload-router request path is only used for subsequent RSC navigations and invalidations, so apps can mix ordinary TanStack SSR loader data and RSC loader data in the same route tree.
-
-## Render Server UI From a Loader
-
-Use `renderServerComponent` when the server output does not need client-provided slots. The loader runs on the server, renders the Server Component to a Flight stream, and returns a value that can be rendered by the client route component.
-
-```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
-Do not return raw JSX from a TanStack Router loader when a client route will consume it. Wrap server-rendered UI with `renderServerComponent` or `createCompositeComponent` so the value can be serialized through TanStack Router's SSR data pipeline.
-:::
-
-## Render Server UI With Client Slots
-
-Use `createCompositeComponent` when server-rendered markup must accept client content, render props, or interactive components. The server component receives slot placeholders, and the client route provides slot implementations through `<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>
-  );
-}
-```
-
-Use `strict` when missing slot implementations should fail fast during development:
-
-```tsx
-<CompositeComponent src={ProductCard} strict />
-```
-
-## Refreshing RSC Data
-
-Because RSC values are TanStack Router data, refresh them with 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>
-  );
-}
-```
-
-If you store RSC values in TanStack Query, disable structural sharing for that query. RSC values are proxies around Flight streams, so deep structural comparison is not meaningful for them.
-
-## Notes
-
-- Server helpers from `*/rsc/server` must only be imported by server code such as loaders or server-only modules.
-- Client routes can render `renderServerComponent` output directly as React nodes.
-- Use `<CompositeComponent>` only for values returned by `createCompositeComponent`.
-- Slot functions should return React nodes and receive serializable arguments. Keep non-serializable objects, request objects, and database handles inside server code.
-- TanStack Router invalidation is the refresh boundary. Avoid building a separate RSC cache outside the router unless the application has a dedicated cache strategy.
-
-## Best Practices
-
-### Prefer Router Data Ownership
-
-Keep RSC values in loader data and let TanStack Router manage cache, hydration, invalidation, and navigation. This keeps the implementation aligned with TanStack Router and avoids a parallel RSC routing layer.
-
-### Use the Smallest Helper That Fits
-
-Use `renderServerComponent` for slotless UI. Use `createCompositeComponent` only when server-rendered markup needs client slots or render props.
-
-### Keep Server and Client Boundaries Clear
-
-Do not import server helpers into client components. Import `CompositeComponent` from the runtime export or from `*/rsc/client`, and import `renderServerComponent` / `createCompositeComponent` only from `*/rsc/server`.
-
-### Automating Changes
-
-When using coding agents or codemods, keep TanStack RSC changes inside the TanStack Router plugin and its RSC helper exports. Do not modify Modern.js core routing or replace the TanStack Router SSR pipeline for this feature.
-
-## Related Links
-
-- [React Server Components (RSC)](/guides/basic-features/render/rsc)
-- [Routing](/guides/basic-features/routes/routes)
-- [Data Cache](/guides/basic-features/data/data-cache)
-- [TanStack Router Documentation](https://tanstack.com/router)

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

@@ -1,226 +0,0 @@
----
-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)