ssr streaming per request

docs/start/framework/react/guide/server-entry-point.md

@@ -89,6 +89,58 @@ export default createServerEntry({
 })
 ```
 
+## Per-request SSR options
+
+The default server entry handler accepts request options as its second argument.
+Use this when you want to keep Start's default handler but override one setting
+for a specific request.
+
+```tsx
+// src/server.ts
+import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
+
+export default createServerEntry({
+  fetch(request) {
+    return handler.fetch(request, {
+      ssr: {
+        streaming: {
+          render: request.headers.get('x-render-stream') !== 'false',
+        },
+      },
+    })
+  },
+})
+```
+
+`ssr.streaming` in request options is a partial override. For example,
+`{ render: false }` disables render streaming for that request.
+
+If you need full handler-level control, create the Start handler yourself:
+
+```tsx
+// src/server.ts
+import {
+  createStartHandler,
+  defaultStreamHandler,
+} from '@tanstack/react-start/server'
+import { createServerEntry } from '@tanstack/react-start/server-entry'
+
+const handler = createStartHandler({
+  handler: defaultStreamHandler,
+  ssr: {
+    streaming: ({ request }) => {
+      if (request.headers.get('user-agent')?.includes('Googlebot')) {
+        return { render: false }
+      }
+
+      return { render: true }
+    },
+  },
+})
+
+export default createServerEntry({ fetch: handler })
+```
+
 ## Server Configuration
 
 The server entry point is where you can configure server-specific behavior:

e2e/react-start/streaming-ssr/package.json

@@ -26,6 +26,7 @@
     "@types/node": "^22.10.2",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^6.0.1",
     "srvx": "^0.11.9",
     "typescript": "^6.0.2",
     "vite": "^8.0.14"

e2e/react-start/streaming-ssr/playwright.config.ts

@@ -8,9 +8,11 @@ const PORT = await getTestServerPort(
   `${packageJson.name}${isPreview ? '_preview' : ''}`,
 )
 const baseURL = `http://localhost:${PORT}`
+const streamingEntryForm =
+  process.env.STREAMING_SSR_ENTRY_FORM ?? 'create-start-handler'
 
-const ssrCommand = `VITE_SERVER_PORT=${PORT} pnpm build && PORT=${PORT} VITE_SERVER_PORT=${PORT} pnpm start`
-const previewCommand = `VITE_SERVER_PORT=${PORT} pnpm build && pnpm preview --port ${PORT}`
+const ssrCommand = `STREAMING_SSR_ENTRY_FORM=${streamingEntryForm} VITE_SERVER_PORT=${PORT} pnpm build && STREAMING_SSR_ENTRY_FORM=${streamingEntryForm} PORT=${PORT} VITE_SERVER_PORT=${PORT} pnpm start`
+const previewCommand = `STREAMING_SSR_ENTRY_FORM=${streamingEntryForm} VITE_SERVER_PORT=${PORT} pnpm build && STREAMING_SSR_ENTRY_FORM=${streamingEntryForm} pnpm preview --port ${PORT}`
 
 /**
  * See https://playwright.dev/docs/test-configuration.

e2e/react-start/streaming-ssr/src/routeTree.gen.ts

@@ -10,6 +10,7 @@
 
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as SyncOnlyRouteImport } from './routes/sync-only'
+import { Route as StreamingPolicyRouteImport } from './routes/streaming-policy'
 import { Route as StreamRouteImport } from './routes/stream'
 import { Route as SlowRenderRouteImport } from './routes/slow-render'
 import { Route as QueryHeavyRouteImport } from './routes/query-heavy'
@@ -26,6 +27,11 @@ const SyncOnlyRoute = SyncOnlyRouteImport.update({
   path: '/sync-only',
   getParentRoute: () => rootRouteImport,
 } as any)
+const StreamingPolicyRoute = StreamingPolicyRouteImport.update({
+  id: '/streaming-policy',
+  path: '/streaming-policy',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const StreamRoute = StreamRouteImport.update({
   id: '/stream',
   path: '/stream',
@@ -88,6 +94,7 @@ export interface FileRoutesByFullPath {
   '/query-heavy': typeof QueryHeavyRoute
   '/slow-render': typeof SlowRenderRoute
   '/stream': typeof StreamRoute
+  '/streaming-policy': typeof StreamingPolicyRoute
   '/sync-only': typeof SyncOnlyRoute
 }
 export interface FileRoutesByTo {
@@ -101,6 +108,7 @@ export interface FileRoutesByTo {
   '/query-heavy': typeof QueryHeavyRoute
   '/slow-render': typeof SlowRenderRoute
   '/stream': typeof StreamRoute
+  '/streaming-policy': typeof StreamingPolicyRoute
   '/sync-only': typeof SyncOnlyRoute
 }
 export interface FileRoutesById {
@@ -115,6 +123,7 @@ export interface FileRoutesById {
   '/query-heavy': typeof QueryHeavyRoute
   '/slow-render': typeof SlowRenderRoute
   '/stream': typeof StreamRoute
+  '/streaming-policy': typeof StreamingPolicyRoute
   '/sync-only': typeof SyncOnlyRoute
 }
 export interface FileRouteTypes {
@@ -130,6 +139,7 @@ export interface FileRouteTypes {
     | '/query-heavy'
     | '/slow-render'
     | '/stream'
+    | '/streaming-policy'
     | '/sync-only'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -143,6 +153,7 @@ export interface FileRouteTypes {
     | '/query-heavy'
     | '/slow-render'
     | '/stream'
+    | '/streaming-policy'
     | '/sync-only'
   id:
     | '__root__'
@@ -156,6 +167,7 @@ export interface FileRouteTypes {
     | '/query-heavy'
     | '/slow-render'
     | '/stream'
+    | '/streaming-policy'
     | '/sync-only'
   fileRoutesById: FileRoutesById
 }
@@ -170,6 +182,7 @@ export interface RootRouteChildren {
   QueryHeavyRoute: typeof QueryHeavyRoute
   SlowRenderRoute: typeof SlowRenderRoute
   StreamRoute: typeof StreamRoute
+  StreamingPolicyRoute: typeof StreamingPolicyRoute
   SyncOnlyRoute: typeof SyncOnlyRoute
 }
 
@@ -182,6 +195,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof SyncOnlyRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/streaming-policy': {
+      id: '/streaming-policy'
+      path: '/streaming-policy'
+      fullPath: '/streaming-policy'
+      preLoaderRoute: typeof StreamingPolicyRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/stream': {
       id: '/stream'
       path: '/stream'
@@ -266,6 +286,7 @@ const rootRouteChildren: RootRouteChildren = {
   QueryHeavyRoute: QueryHeavyRoute,
   SlowRenderRoute: SlowRenderRoute,
   StreamRoute: StreamRoute,
+  StreamingPolicyRoute: StreamingPolicyRoute,
   SyncOnlyRoute: SyncOnlyRoute,
 }
 export const routeTree = rootRouteImport

e2e/react-start/streaming-ssr/src/routes/index.tsx

@@ -52,6 +52,12 @@ function Index() {
           </Link>{' '}
           - Tests nested components with deferred data
         </li>
+        <li>
+          <Link to="/streaming-policy" data-testid="link-streaming-policy">
+            Streaming Policy
+          </Link>{' '}
+          - Tests request-controlled SSR streaming policy
+        </li>
       </ul>
     </div>
   )

e2e/react-start/streaming-ssr/src/routes/streaming-policy.tsx

@@ -0,0 +1,41 @@
+import { Await, createFileRoute, useRouter } from '@tanstack/react-router'
+import { Suspense } from 'react'
+
+export const Route = createFileRoute('/streaming-policy')({
+  loader: () => {
+    return {
+      immediate: 'Immediate policy content',
+      deferred: new Promise<string>((resolve) => {
+        setTimeout(() => resolve('Deferred policy content'), 100)
+      }),
+    }
+  },
+  component: StreamingPolicyRoute,
+})
+
+function StreamingPolicyRoute() {
+  const router = useRouter()
+  const loaderData = Route.useLoaderData()
+  const serverSsr = router.serverSsr
+  const render = serverSsr?.shouldStream('render')
+  const head = serverSsr?.shouldStream('head')
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <h2>Streaming Policy Test</h2>
+      <div data-testid="policy-render" suppressHydrationWarning>
+        {String(render)}
+      </div>
+      <div data-testid="policy-head" suppressHydrationWarning>
+        {String(head)}
+      </div>
+      <div data-testid="policy-immediate">{loaderData.immediate}</div>
+      <Suspense fallback={<div>Loading policy content...</div>}>
+        <Await
+          promise={loaderData.deferred}
+          children={(value) => <div data-testid="policy-deferred">{value}</div>}
+        />
+      </Suspense>
+    </div>
+  )
+}

e2e/react-start/streaming-ssr/src/server.ts

@@ -0,0 +1,67 @@
+import {
+  createStartHandler,
+  defaultStreamHandler,
+} from '@tanstack/react-start/server'
+import defaultServerEntry, {
+  createServerEntry,
+} from '@tanstack/react-start/server-entry'
+import type { SsrStreamingResolverResult } from '@tanstack/react-start/server'
+
+type SsrStreamingOverride = {
+  render?: boolean
+  head?: boolean
+}
+
+function getStreamingPolicy(request: Request): SsrStreamingResolverResult {
+  const url = new URL(request.url)
+
+  switch (url.searchParams.get('streaming')) {
+    case 'all':
+      return {
+        render: true,
+        head: true,
+      }
+    case 'none':
+      return {
+        render: false,
+      }
+    case 'render-only':
+      return {
+        render: true,
+      }
+    case 'head-only':
+      return {
+        render: false,
+        head: true,
+      }
+    default:
+      return undefined
+  }
+}
+
+function getStreamingOverride(
+  request: Request,
+): SsrStreamingOverride | undefined {
+  return getStreamingPolicy(request)
+}
+
+const handler = createStartHandler({
+  handler: defaultStreamHandler,
+  ssr: {
+    streaming: ({ request }) => getStreamingPolicy(request),
+  },
+})
+
+export default createServerEntry({
+  fetch(request) {
+    if (process.env.STREAMING_SSR_ENTRY_FORM === 'default-entry') {
+      return defaultServerEntry.fetch(request, {
+        ssr: {
+          streaming: getStreamingOverride(request),
+        },
+      } as any)
+    }
+
+    return handler(request)
+  },
+})

e2e/react-start/streaming-ssr/tests/deferred.spec.ts

@@ -1,6 +1,13 @@
 import { expect, test, testWithHydration } from './fixtures'
+import { expectDeferredRouteToStream } from '../../../streaming-ssr-assertions'
 
 test.describe('Deferred data streaming', () => {
+  test('streams the shell before deferred data resolves', async ({
+    baseURL,
+  }) => {
+    await expectDeferredRouteToStream(baseURL, { expectFallback: true })
+  })
+
   test('shows immediate data right away and deferred data after loading', async ({
     page,
   }) => {

e2e/react-start/streaming-ssr/tests/home.spec.ts

@@ -17,6 +17,7 @@ test.describe('Home page', () => {
       await expect(
         page.getByRole('link', { name: 'Stream' }).first(),
       ).toBeVisible()
+      await expect(page.getByTestId('link-streaming-policy')).toBeVisible()
     },
   )
 

e2e/react-start/streaming-ssr/tests/preview-streaming.spec.ts

@@ -1,5 +1,7 @@
 import { expect, test } from './fixtures'
 
+test.skip(process.env.MODE !== 'preview', 'Only runs against vite preview')
+
 test('vite preview streams HTML incrementally', async ({ page }) => {
   // /deferred has immediate data + deferred data with a ~1s delay.
   // Without streaming, compression buffers the entire response.

e2e/react-start/streaming-ssr/tests/query-heavy.spec.ts

@@ -1,6 +1,13 @@
 import { expect, test, testWithHydration } from './fixtures'
+import { expectQueryHeavyRouteToStream } from '../../../streaming-ssr-assertions'
 
 test.describe('Query heavy route (9 useSuspenseQuery)', () => {
+  test('streams fast query reveals before slow queries resolve', async ({
+    baseURL,
+  }) => {
+    await expectQueryHeavyRouteToStream(baseURL)
+  })
+
   test('all queries resolve with server data', async ({ page }) => {
     await page.goto('/query-heavy')
 

e2e/react-start/streaming-ssr/tests/streaming-policy.spec.ts

@@ -0,0 +1,49 @@
+import { expect, test } from './fixtures'
+
+const streamingEntryForm =
+  process.env.STREAMING_SSR_ENTRY_FORM ?? 'create-start-handler'
+
+test.describe(`ssr.streaming policy (${streamingEntryForm})`, () => {
+  test('resolves render and head channels from the request', async ({
+    request,
+  }) => {
+    const cases = [
+      ['all', 'true', 'true'],
+      ['none', 'false', 'false'],
+      ['render-only', 'true', 'false'],
+      ['head-only', 'false', 'true'],
+    ] as const
+
+    for (const [mode, render, head] of cases) {
+      const response = await request.get(`/streaming-policy?streaming=${mode}`)
+      const html = await response.text()
+
+      expect(response.ok()).toBe(true)
+      expect(html).toContain(`<div data-testid="policy-render">${render}</div>`)
+      expect(html).toContain(`<div data-testid="policy-head">${head}</div>`)
+    }
+  })
+
+  test.describe('with JavaScript disabled', () => {
+    test.use({ javaScriptEnabled: false })
+
+    for (const mode of ['none', 'head-only'] as const) {
+      test(`renders the full policy page when streaming=${mode}`, async ({
+        page,
+      }) => {
+        await page.goto(`/streaming-policy?streaming=${mode}`)
+
+        await expect(page.getByTestId('policy-render')).toContainText('false')
+        await expect(page.getByTestId('policy-head')).toContainText(
+          mode === 'head-only' ? 'true' : 'false',
+        )
+        await expect(page.getByTestId('policy-immediate')).toContainText(
+          'Immediate policy content',
+        )
+        await expect(page.getByTestId('policy-deferred')).toContainText(
+          'Deferred policy content',
+        )
+      })
+    }
+  })
+})