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

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

@@ -0,0 +1,267 @@
+# Streaming Server-Side Rendering
+
+Streaming rendering is an advanced rendering method that progressively returns content during the page rendering process, significantly improving user experience.
+
+In traditional SSR rendering, the page is rendered all at once, requiring all data to be loaded before returning the complete HTML. In streaming rendering, the page is rendered progressively, allowing content to be returned as it renders, so users can see initial content faster.
+
+:::info Default Mode
+**Streaming SSR is the default rendering mode for Modern.js SSR**. When you enable SSR, streaming rendering is available without additional configuration.
+
+If you need to switch to traditional SSR mode (waiting for all data to load before returning at once), you can configure `server.ssr.mode` to `'string'`. For detailed information, refer to the [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr) documentation.
+:::
+
+Compared to traditional SSR rendering:
+
+- **Faster Perceived Speed**: Streaming rendering can progressively display content, quickly rendering the home page.
+- **Enhanced User Experience**: Users can see page content faster and interact without waiting for the entire page to render.
+- **Better Performance Control**: Developers can better control the loading priority and order, optimizing performance and user experience.
+- **Better Adaptability**: Streaming rendering adapts better to various network speeds and device performance, ensuring good performance across different environments.
+
+## Enabling Streaming Rendering
+
+Modern.js supports React 18+ streaming rendering. When you enable SSR, streaming rendering is enabled by default:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true, // Streaming rendering enabled by default
+  },
+});
+```
+
+If you need to explicitly specify streaming rendering mode, you can configure:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream', // Explicitly specify streaming rendering mode
+    },
+  },
+});
+```
+
+Modern.js streaming rendering is based on React Router and involves several key APIs:
+
+- [`Await`](https://reactrouter.com/en/main/components/await): Used to render the asynchronous data returned by the Data Loader.
+- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value): Used to fetch data from the nearest parent `Await` component.
+
+## Fetching Data
+
+```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 });
+};
+```
+
+Here, `user` is a Promise object representing asynchronously fetched data, processed using `defer`. Notice that `defer` must receive an object parameter; a direct Promise cannot be passed.
+
+Additionally, `defer` can receive both asynchronous and synchronous data. In the example below, short-duration requests are returned using object data, while longer-duration requests are returned using a 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,
+  });
+};
+```
+
+This way, the application can prioritize displaying partially available content without waiting for the most time-consuming data requests.
+
+## Rendering Data
+
+To render the asynchronous data returned by the Data Loader, use the `Await` component. For example:
+
+```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;
+```
+
+The `Await` component needs to be wrapped inside a `Suspense` component. The `resolve` prop of `Await` should be the asynchronously fetched data from the Data Loader. When the data is fetched, it will be rendered using the [Render Props](https://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) pattern. During data fetching, the content set by the `fallback` prop of `Suspense` is displayed.
+
+:::warning Warning
+When importing types from the `page.data.ts` file, use `import type` to ensure only type information is imported, preventing Data Loader code from being bundled into the frontend.
+:::
+
+In the component, you can also fetch asynchronous data returned by the Data Loader using `useAsyncValue`. For example:
+
+```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;
+```
+
+## Error Handling
+
+The `errorElement` prop of the `Await` component handles errors in Data Loader or sub-component rendering. For example, intentionally throwing an error in the Data Loader function:
+
+```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 });
+};
+```
+
+Then, fetch the error using `useAsyncError` and set a component to render the error message for the `errorElement` prop of the `Await` component:
+
+```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>;
+}
+```
+
+## Controlling When to Wait for Full HTML
+
+Streaming improves perceived speed, but in some cases (SEO crawlers, A/B buckets, compliance pages) you may want to wait for all content before sending the response.
+
+Modern.js decides the streaming mode with this priority:
+
+1. Request header `x-should-stream-all` (set per-request in middleware).
+2. Env `MODERN_JS_STREAM_TO_STRING` (forces full HTML).
+3. [isbot](https://www.npmjs.com/package/isbot) check on `user-agent` (bots get full HTML).
+4. Default: stream shell first.
+
+Set the header in your middleware to choose the behavior dynamically:
+
+```ts title="middleware example"
+export const middleware = async (ctx, next) => {
+  const ua = ctx.req.header('user-agent') || '';
+  const shouldWaitAll = /Lighthouse|Googlebot/i.test(ua) || ctx.req.path === '/marketing';
+
+  // Write a boolean string: true -> onAllReady, false -> onShellReady
+  ctx.req.headers.set('x-should-stream-all', String(shouldWaitAll));
+
+  await next();
+};
+```
+
+import StreamSSRPerformance from '@site-docs-en/components/stream-ssr-performance';
+
+<StreamSSRPerformance />
+
+## Related Documentation
+
+- [Rendering Mode Overview](/guides/basic-features/render/overview)
+- [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr)
+- [Rendering Cache](/guides/basic-features/render/ssr-cache)
+- [React Server Components (RSC)](/guides/basic-features/render/rsc) - Use with Streaming SSR
+- [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37) - React 18 Architecture Overview

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

@@ -0,0 +1,226 @@
+---
+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/en/guides/basic-features/routes/_meta.json

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