Skip to main content

Transports

Your chat must get chunks from the server to the UI. The best way to do that depends on where your code runs: a web server, an edge runtime, a phone, or one process.

TanStack AI works with all of them. A connection adapter is the only part that touches the network. Chunk processing, messages, tool calls, and UI updates work the same on every transport.

Pass the adapter to useChat as connection:

import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

const { messages, sendMessage } = useChat({
  connection: fetchServerSentEvents("/api/chat"),
});

For the full server and client path, see Streaming.

Pick a transport

You haveUsePage
A normal HTTP serverfetchServerSentEventsServer-Sent Events
A runtime or proxy that blocks SSEfetchHttpStreamHTTP Stream
A host or proxy that buffers or breaks streams, or you want one response per runfetchJsonJSON
React Native or ExpoxhrHttpStream or xhrServerSentEventsReact Native
A function that returns an AsyncIterable<StreamChunk> synchronously (in-process chat(), an RSC stream, tests)streamServer Functions
An async function, such as a TanStack Start server function, that resolves to a Response or an AsyncIterable<StreamChunk>fetcherServer Functions
An RPC framework such as Cap'n Web, gRPC-Web, or tRPCrpcStreamServer Functions
One long-lived, resumable WebSocket for many runswebSocketWebSockets
BroadcastChannel, postMessage, a shared worker, or a different persistent channelYour own subscribe / send adapterCustom Transports
SSE with a wrapped fetch (auth refresh, retries)fetchServerSentEvents with fetchClientRequest Options
A different protocol, such as HTTP/3Your own connect adapterCustom Transports

All adapters produce the same StreamChunk events (AG-UI Protocol). The choice changes only the transport.

To send headers, a request body, or an auth token, see Request Options.

Cancel a run

Every adapter gets an AbortSignal. The stop() function from useChat triggers the signal and aborts the active run:

import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

const { stop } = useChat({ connection: fetchServerSentEvents("/api/chat") });
stop(); // aborts the active stream
  • Built-in adapters pass the signal to fetch.
  • Custom adapters must honor the signal themselves.
  • SubscribeConnectionAdapter: the signal in subscribe() ends the full subscription (for example, on unmount). The signal in send() ends only the active send.

The fetch adapters cancel the response body in these cases:

  • Parsing fails.
  • You exit the chunk iterator early.
  • The SSE adapter receives a [DONE] marker.

A response that gets to its normal end keeps all of its chunks.

Custom cancellation hooks do not delay errors or early iterator returns. The adapters release the reader lock, also when cancellation fails or stays pending.

Errors

An adapter throws on a transport error: an HTTP status that is not 2xx, a parse failure, or a dropped socket. The ChatClient catches the error. If no RUN_ERROR chunk was emitted yet, the client emits one. Then it shows the error through onError and the error state:

import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

const { error } = useChat({
  connection: fetchServerSentEvents("/api/chat"),
  onError: (err) => console.error("Chat failed:", err),
});

If the connection drops in the middle of a line, the stream adapters throw StreamTruncatedError.

Do not catch and hide an AbortError in a custom adapter. Let it propagate, so that the client knows the abort worked.

Best practices

  • Start with SSE. It works in the most places and is the easiest to debug. Change only when something blocks it.
  • Use stream() when you can. If you control both sides and do not need HTTP, a server function takes less code than a custom adapter.
  • Use subscribe / send only for a persistent channel. Then you must handle reconnection, run correlation, and the connection lifecycle yourself.
  • Always honor abortSignal. The client uses it to clean up on unmount and on stop().
  • Emit RUN_FINISHED from the server. Without it, the client does not know that the turn ended. See Stream Events.

For the full type signatures, see API Reference: @tanstack/ai-client.

Pick a row in the table and send a message. The reply streams into messages on every transport.

Edit on GitHub