feat(ai-client,ai-react): add fetcher option to ChatClient/useChat

.changeset/usechat-fetcher-server-functions.md

@@ -0,0 +1,23 @@
+---
+'@tanstack/ai-client': minor
+'@tanstack/ai-react': minor
+'@tanstack/ai-preact': patch
+'@tanstack/ai-solid': patch
+'@tanstack/ai-svelte': patch
+'@tanstack/ai-vue': patch
+---
+
+Add a `fetcher` option to `ChatClient` and the framework chat hooks
+(`useChat` / `createChat`), mirroring the `fetcher` option on the
+generation hooks. Pass either `connection` or `fetcher` — the XOR is
+enforced at the type level via `ChatTransport`.
+
+```ts
+useChat({
+  fetcher: ({ messages }, { signal }) => chatFn({ data: { messages }, signal }),
+})
+```
+
+The fetcher may return either a `Response` (parsed as SSE) or an
+`AsyncIterable<StreamChunk>` (yielded directly). `stream()`,
+`fetchServerSentEvents`, `fetchHttpStream`, and `rpcStream` are unchanged.

examples/ts-react-chat/src/components/Header.tsx

@@ -11,6 +11,7 @@ import {
   Menu,
   Mic,
   Music,
+  Server,
   Video,
   X,
 } from 'lucide-react'
@@ -197,6 +198,19 @@ export default function Header() {
             <Mic size={20} />
             <span className="font-medium">Voice Chat (Realtime)</span>
           </Link>
+
+          <Link
+            to="/server-fn-chat"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-2"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-cyan-600 hover:bg-cyan-700 transition-colors mb-2',
+            }}
+          >
+            <Server size={20} />
+            <span className="font-medium">Server Function Chat</span>
+          </Link>
         </nav>
       </aside>
     </>

examples/ts-react-chat/src/lib/server-fns.ts

@@ -1,6 +1,7 @@
 import { createServerFn } from '@tanstack/react-start'
 import { z } from 'zod'
 import {
+  chat,
   generateAudio,
   generateImage,
   generateSpeech,
@@ -10,7 +11,13 @@ import {
   summarize,
   toServerSentEventsResponse,
 } from '@tanstack/ai'
-import { openaiImage, openaiSummarize, openaiVideo } from '@tanstack/ai-openai'
+import {
+  openaiImage,
+  openaiSummarize,
+  openaiText,
+  openaiVideo,
+} from '@tanstack/ai-openai'
+import type { UIMessage } from '@tanstack/ai'
 import {
   InvalidModelOverrideError,
   UnknownProviderError,
@@ -365,3 +372,23 @@ export const generateVideoStreamFn = createServerFn({ method: 'POST' })
       }),
     )
   })
+
+// =============================================================================
+// Chat server function — pairs with useChat({ fetcher })
+// =============================================================================
+
+export const chatFn = createServerFn({ method: 'POST' })
+  .inputValidator(
+    (data: { messages: Array<UIMessage>; data?: Record<string, any> }) => data,
+  )
+  .handler(({ data }) =>
+    toServerSentEventsResponse(
+      chat({
+        adapter: openaiText('gpt-5.2'),
+        messages: data.messages as any,
+        systemPrompts: [
+          'You are a helpful assistant. Keep replies short and friendly.',
+        ],
+      }),
+    ),
+  )

examples/ts-react-chat/src/routeTree.gen.ts

@@ -9,6 +9,7 @@
 // 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 ServerFnChatRouteImport } from './routes/server-fn-chat'
 import { Route as RealtimeRouteImport } from './routes/realtime'
 import { Route as ImageGenRouteImport } from './routes/image-gen'
 import { Route as IndexRouteImport } from './routes/index'
@@ -31,6 +32,11 @@ import { Route as ApiGenerateSpeechRouteImport } from './routes/api.generate.spe
 import { Route as ApiGenerateImageRouteImport } from './routes/api.generate.image'
 import { Route as ApiGenerateAudioRouteImport } from './routes/api.generate.audio'
 
+const ServerFnChatRoute = ServerFnChatRouteImport.update({
+  id: '/server-fn-chat',
+  path: '/server-fn-chat',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const RealtimeRoute = RealtimeRouteImport.update({
   id: '/realtime',
   path: '/realtime',
@@ -143,6 +149,7 @@ export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/image-gen': typeof ImageGenRoute
   '/realtime': typeof RealtimeRoute
+  '/server-fn-chat': typeof ServerFnChatRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -166,6 +173,7 @@ export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/image-gen': typeof ImageGenRoute
   '/realtime': typeof RealtimeRoute
+  '/server-fn-chat': typeof ServerFnChatRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -190,6 +198,7 @@ export interface FileRoutesById {
   '/': typeof IndexRoute
   '/image-gen': typeof ImageGenRoute
   '/realtime': typeof RealtimeRoute
+  '/server-fn-chat': typeof ServerFnChatRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -215,6 +224,7 @@ export interface FileRouteTypes {
     | '/'
     | '/image-gen'
     | '/realtime'
+    | '/server-fn-chat'
     | '/api/image-gen'
     | '/api/structured-output'
     | '/api/summarize'
@@ -238,6 +248,7 @@ export interface FileRouteTypes {
     | '/'
     | '/image-gen'
     | '/realtime'
+    | '/server-fn-chat'
     | '/api/image-gen'
     | '/api/structured-output'
     | '/api/summarize'
@@ -261,6 +272,7 @@ export interface FileRouteTypes {
     | '/'
     | '/image-gen'
     | '/realtime'
+    | '/server-fn-chat'
     | '/api/image-gen'
     | '/api/structured-output'
     | '/api/summarize'
@@ -285,6 +297,7 @@ export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   ImageGenRoute: typeof ImageGenRoute
   RealtimeRoute: typeof RealtimeRoute
+  ServerFnChatRoute: typeof ServerFnChatRoute
   ApiImageGenRoute: typeof ApiImageGenRoute
   ApiStructuredOutputRoute: typeof ApiStructuredOutputRoute
   ApiSummarizeRoute: typeof ApiSummarizeRoute
@@ -307,6 +320,13 @@ export interface RootRouteChildren {
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/server-fn-chat': {
+      id: '/server-fn-chat'
+      path: '/server-fn-chat'
+      fullPath: '/server-fn-chat'
+      preLoaderRoute: typeof ServerFnChatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/realtime': {
       id: '/realtime'
       path: '/realtime'
@@ -461,6 +481,7 @@ const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   ImageGenRoute: ImageGenRoute,
   RealtimeRoute: RealtimeRoute,
+  ServerFnChatRoute: ServerFnChatRoute,
   ApiImageGenRoute: ApiImageGenRoute,
   ApiStructuredOutputRoute: ApiStructuredOutputRoute,
   ApiSummarizeRoute: ApiSummarizeRoute,

examples/ts-react-chat/src/routes/server-fn-chat.tsx

@@ -0,0 +1,101 @@
+import { useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { useChat } from '@tanstack/ai-react'
+import { Send, Square } from 'lucide-react'
+import { chatFn } from '@/lib/server-fns'
+
+export const Route = createFileRoute('/server-fn-chat')({
+  component: ServerFnChat,
+})
+
+function ServerFnChat() {
+  const { messages, sendMessage, isLoading, error, stop } = useChat({
+    fetcher: ({ messages }, { signal }) =>
+      chatFn({ data: { messages }, signal }),
+  })
+  const [input, setInput] = useState('')
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!input.trim() || isLoading) return
+    void sendMessage(input)
+    setInput('')
+  }
+
+  return (
+    <div className="flex flex-col h-[calc(100vh-72px)] bg-gray-950 text-gray-100">
+      <div className="border-b border-gray-800 bg-gray-900/60 px-4 py-3">
+        <h2 className="text-lg font-semibold">Chat via server function</h2>
+        <p className="text-xs text-gray-400 mt-1">
+          <code className="text-cyan-400">
+            useChat(&#123; fetcher: ({'{'}messages{'}'}, {'{'}signal{'}'}) =&gt;
+            chatFn({'{'} data, signal {'}'}) &#125;)
+          </code>{' '}
+          — the server function returns an SSE{' '}
+          <code className="text-cyan-400">Response</code>; the chat client
+          parses it.
+        </p>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-4 space-y-3">
+        {messages.length === 0 && (
+          <p className="text-gray-500 text-sm">
+            Say something to start the chat.
+          </p>
+        )}
+        {messages.map((m) => (
+          <div
+            key={m.id}
+            className={`max-w-2xl rounded-lg px-3 py-2 ${
+              m.role === 'user'
+                ? 'ml-auto bg-cyan-700/40 border border-cyan-600/40'
+                : 'mr-auto bg-gray-800 border border-gray-700'
+            }`}
+          >
+            {m.parts.map((part, i) =>
+              part.type === 'text' ? <span key={i}>{part.content}</span> : null,
+            )}
+          </div>
+        ))}
+        {error && (
+          <div className="rounded-lg border border-red-700/60 bg-red-900/30 px-3 py-2 text-sm text-red-200">
+            {error.message}
+          </div>
+        )}
+      </div>
+
+      <form
+        onSubmit={handleSubmit}
+        className="border-t border-gray-800 bg-gray-900/80 p-3 flex gap-2"
+      >
+        <input
+          type="text"
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Message..."
+          disabled={isLoading}
+          className="flex-1 rounded-lg bg-gray-800 border border-gray-700 px-3 py-2 text-sm focus:outline-none focus:border-cyan-500"
+        />
+        {isLoading ? (
+          <button
+            type="button"
+            onClick={stop}
+            className="px-3 py-2 rounded-lg bg-red-600 hover:bg-red-700 text-white"
+            aria-label="Stop"
+          >
+            <Square size={18} />
+          </button>
+        ) : (
+          <button
+            type="submit"
+            disabled={!input.trim()}
+            className="px-3 py-2 rounded-lg bg-cyan-600 hover:bg-cyan-700 disabled:opacity-50 text-white"
+            aria-label="Send"
+          >
+            <Send size={18} />
+          </button>
+        )}
+      </form>
+    </div>
+  )
+}

packages/typescript/ai-client/src/chat-client.ts

@@ -4,7 +4,10 @@ import {
   normalizeToUIMessage,
 } from '@tanstack/ai'
 import { DefaultChatClientEventEmitter } from './events'
-import { normalizeConnectionAdapter } from './connection-adapters'
+import {
+  fetcherToConnectionAdapter,
+  normalizeConnectionAdapter,
+} from './connection-adapters'
 import type {
   AnyClientTool,
   ContentPart,
@@ -19,13 +22,34 @@ import type { ChatClientEventEmitter } from './events'
 import type {
   ChatClientOptions,
   ChatClientState,
+  ChatFetcher,
   ConnectionStatus,
   MessagePart,
   MultimodalContent,
   ToolCallPart,
   UIMessage,
 } from './types'
 
+function resolveTransport(transport: {
+  connection?: ConnectionAdapter
+  fetcher?: ChatFetcher
+}): ConnectionAdapter {
+  const hasConnection = transport.connection !== undefined
+  const hasFetcher = transport.fetcher !== undefined
+  if (hasConnection && hasFetcher) {
+    throw new Error(
+      'ChatClient: pass either `connection` or `fetcher`, not both.',
+    )
+  }
+  if (hasConnection) {
+    return transport.connection!
+  }
+  if (hasFetcher) {
+    return fetcherToConnectionAdapter(transport.fetcher!)
+  }
+  throw new Error('ChatClient: either `connection` or `fetcher` is required.')
+}
+
 export class ChatClient {
   private processor: StreamProcessor
   private connection: SubscribeConnectionAdapter
@@ -82,7 +106,7 @@ export class ChatClient {
   constructor(options: ChatClientOptions) {
     this.uniqueId = options.id || this.generateUniqueId('chat')
     this.body = options.body || {}
-    this.connection = normalizeConnectionAdapter(options.connection)
+    this.connection = normalizeConnectionAdapter(resolveTransport(options))
     this.events = new DefaultChatClientEventEmitter(this.uniqueId)
 
     // Build client tools map
@@ -969,6 +993,7 @@ export class ChatClient {
    */
   updateOptions(options: {
     connection?: ConnectionAdapter
+    fetcher?: ChatFetcher
     body?: Record<string, any>
     tools?: ReadonlyArray<AnyClientTool>
     onResponse?: (response?: Response) => void | Promise<void>
@@ -984,7 +1009,7 @@ export class ChatClient {
       context: { toolCallId?: string },
     ) => void
   }): void {
-    if (options.connection !== undefined) {
+    if (options.connection !== undefined || options.fetcher !== undefined) {
       const wasSubscribed = this.isSubscribed
 
       if (this.isLoading) {
@@ -999,7 +1024,12 @@ export class ChatClient {
       this.resetSessionGenerating()
       this.setIsSubscribed(false)
       this.setConnectionStatus('disconnected')
-      this.connection = normalizeConnectionAdapter(options.connection)
+      this.connection = normalizeConnectionAdapter(
+        resolveTransport({
+          connection: options.connection,
+          fetcher: options.fetcher,
+        }),
+      )
 
       if (wasSubscribed) {
         this.subscribe()