examples: Add a new TanStack Start example for typed readable streams

docs/router/framework/react/guide/streaming-data-from-server-functions.md

@@ -0,0 +1,97 @@
+---
+title: Streaming Data from Server Functions
+---
+
+Streaming data from the server has become very popular thanks to the rise of AI apps. Luckily, it's a pretty easy task with TanStack Start, and what's even better: the streamed data is typed!
+
+The two most popular ways of streaming data from server functions are using `ReadableStream`-s or async generators.
+
+You can see how to implement both in the [Streaming Data From Server Functions example](https://github.com/TanStack/router/tree/main/examples/react/start-streaming-data-from-server-functions).
+
+## Typed Readable Streams
+
+Here's an example for a server function that streams an array of messages to the client in a type-safe manner:
+
+```ts
+type Message = {
+  content: string
+}
+
+/**
+  This server function returns a `ReadableStream`
+  that streams `Message` chunks to the client.
+*/
+const streamingResponseFn = createServerFn().handler(async () => {
+  // These are the messages that you want to send as chunks to the client
+  const messages: Message[] = generateMessages()
+
+  // This `ReadableStream` is typed, so each
+  // will be of type `Message`.
+  const stream = new ReadableStream<Message>({
+    async start(controller) {
+      for (const message of messages) {
+        // Send the message
+        controller.enqueue(message)
+      }
+      controller.close()
+    },
+  })
+
+  return stream
+})
+```
+
+When you consume this stream from the client, the streamed chunks will be properly typed:
+
+```ts
+const [message, setMessage] = useState('')
+
+const getTypedReadableStreamResponse = useCallback(async () => {
+  const response = await streamingResponseFn()
+
+  if (!response) {
+    return
+  }
+
+  const reader = response.getReader()
+  let done = false
+  while (!done) {
+    const { value, done: doneReading } = await reader.read()
+    done = doneReading
+    if (value) {
+      // Notice how we know the value of `chunk` (`Message | undefined`)
+      // here, because it's coming from the typed `ReadableStream`
+      const chunk = value.content
+      setMessage((prev) => prev + chunk)
+    }
+  }
+}, [])
+```
+
+## Async Generators in Server Functions
+
+A much cleaner approach with the same results is to use an async generator function:
+
+```ts
+const streamingWithAnAsyncGeneratorFn = createServerFn().handler(
+  async function* () {
+    const messages: Message[] = generateMessages()
+    for (const msg of messages) {
+      await sleep(500)
+      // The streamed chunks are still typed as `Message`
+      yield msg
+    }
+  },
+)
+```
+
+The client side code will also be leaner:
+
+```ts
+const getResponseFromTheAsyncGenerator = useCallback(async () => {
+  for await (const msg of await streamingWithAnAsyncGeneratorFn()) {
+    const chunk = msg.content
+    setMessages((prev) => prev + chunk)
+  }
+}, [])
+```

docs/start/framework/react/server-functions.md

@@ -204,9 +204,13 @@ Access request headers, cookies, and response customization:
 - `setResponseHeader()` - Set custom response headers
 - `setResponseStatus()` - Custom status codes
 
-### Streaming & Raw Responses
+### Streaming
 
-Return `Response` objects for streaming, binary data, or custom content types.
+Stream typed data from server functions to the client. See the [Streaming Data from Server Functions guide](../guide/streaming-data-from-server-functions).
+
+### Raw Responses
+
+Return `Response` objects binary data, or custom content types.
 
 ### Progressive Enhancement
 

examples/react/start-streaming-data-from-server-functions/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "tanstack-start-streaming-data-from-server-functions",
+  "private": true,
+  "sideEffects": false,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && tsc --noEmit",
+    "start": "vite start"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "^1.132.33",
+    "@tanstack/react-router-devtools": "^1.132.33",
+    "@tanstack/react-start": "^1.132.36",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "vite": "^7.1.7",
+    "vite-tsconfig-paths": "^5.1.4"
+  }
+}

examples/react/start-streaming-data-from-server-functions/src/routeTree.gen.ts

@@ -0,0 +1,68 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/'
+  id: '__root__' | '/'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}

examples/react/start-streaming-data-from-server-functions/src/router.tsx

@@ -0,0 +1,20 @@
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    defaultPreload: 'intent',
+    defaultErrorComponent: (err) => <p>{err.error.stack}</p>,
+    defaultNotFoundComponent: () => <p>not found</p>,
+    scrollRestoration: true,
+  })
+
+  return router
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}

examples/react/start-streaming-data-from-server-functions/src/routes/__root.tsx

@@ -0,0 +1,41 @@
+/// <reference types="vite/client" />
+import * as React from 'react'
+import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+import {
+  HeadContent,
+  Link,
+  Outlet,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/react-router'
+import appCss from '~/styles/app.css?url'
+
+export const Route = createRootRoute({
+  head: () => ({
+    links: [{ rel: 'stylesheet', href: appCss }],
+  }),
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <RootDocument>
+      <Outlet />
+    </RootDocument>
+  )
+}
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <TanStackRouterDevtools position="bottom-right" />
+        <Scripts />
+      </body>
+    </html>
+  )
+}