TanStack AI + Effect 4: The First-Party Adapter Explained (0.1.0)

TanStack AI shipped @tanstack/ai-effect 0.1.0: AI.chat returns a typed Effect Stream, errors are typed, and interruption aborts the model request. Install, server route, and client wiring explained.

Huifer
Huifer
November 7, 20269 min read
Also available in:Deutsch · 中文

Written by Huifer, solo developer and maintainer of TanStack Ship. I run streaming chat and tool-calling agents in production SaaS apps built on TanStack Start, and I have hit the failure modes of untyped streaming SDKs first-hand — silent error swallowing, orphaned model requests after the client disconnects, and retry logic bolted on after the fact. This guide breaks down @tanstack/ai-effect, which is a first-party Effect 4 binding for TanStack AI: AI.chat returns a typed Stream, and every activity runs as an Effect or Stream. Everything here uses only the official docs and the published package metadata.

Verified sources: TanStack AI Effect docs · @tanstack/ai-effect on npm · TanStack AI docs · Effect 4 docs · TanStack AI repo · TanStack Ship features

Last updated: 2026-11-07 · Changelog

TanStack AI + Effect 4: The First-Party Adapter Explained

TanStack AI now ships a first-party Effect adapter for your AI apps, and if you build streaming chat on an Effect 4 server, this guide is for you — no more choosing between your effect runtime and the AI SDK. a first-party Effect adapter: @tanstack/ai-effect (published 2026-11-06, currently 0.1.0). The one-line pitch from the official README: Effect 4 bindings for TanStack AI — every activity as an Effect or Stream, plus Effect server tools. If your server code is written in Effect 4, you no longer choose between your effect runtime and TanStack's AI SDK.

TL;DR (for TypeScript teams running Effect 4 on the server): @tanstack/ai-effect is a first-party Effect 4 binding for TanStack AI. Core chat() returns an async iterable and throws plain errors, which does not compose inside an Effect program. AI.chat from @tanstack/ai-effect returns a Stream<StreamChunk, AIError> instead — typed errors, Stream combinators, and interruption that actually aborts the model request. Install @tanstack/ai @tanstack/ai-effect @tanstack/ai-openai @tanstack/ai-react effect, wrap your server route with Stream.toAsyncIterable, and keep useChat on the client unchanged.

What it is: @tanstack/ai-effect is a first-party Effect 4 binding for the TanStack AI SDK, published as 0.1.0 on 2026-11-06. This guide is for TypeScript teams whose server layer already runs Effect 4 and who want streaming chat, tool calls, and structured outputs typed into their Effect error channels. How to decide in one line: if your server imports effect today, adopt the adapter; if it does not, core chat() is simpler. This guide covers the install, the server route, the client wiring, and the adoption decision; out of scope are provider-side pricing and prompt engineering.

Why a separate adapter package exists

Some history for context: TanStack AI entered its RC phase in 2026, reached 1.0 with the "Still Your AI, Still Your Way" release, and has been moving fast since 2026 — 1.1.0 landed on 2026-11-05 and 1.2.0 followed within days. The Effect adapter is the newest surface: npm recorded all three of its first publishes (0.0.0-stage, 0.0.0, 0.1.0) inside a single 19-minute window on 2026-11-06, and the docs site gained its Effect section the same day.

The core chat() function in @tanstack/ai is runtime-agnostic by design: it returns an async iterable of chunks and throws plain Errors. That is the right default for a plain TypeScript server, but it breaks two contracts that Effect programs care about:

  • Errors are untyped. In Effect, errors live in the channel type (Stream<Chunk, Error>). A thrown error escapes your typed error flow and lands in whatever generic catch-all wraps the fiber.
  • No structured interruption. Effect manages interruption through fibers. An async iterable does not know how to cancel an in-flight model request when the fiber is interrupted — the connection to the provider just leaks.

@tanstack/ai-effect fixes both. AI.chat returns Stream<StreamChunk, AIError>, and per the official docs: "If the browser closes the request, the stream stops. Then AI.chat aborts the request to the model." That last part is the production detail that matters — aborting the downstream SSE un-aborts nothing upstream unless the adapter wires it, and this adapter does.

Install

The package needs Effect 4 (effect 4.1 or later) and @tanstack/ai 1.2.0+ as peer dependencies:

bash
npm i @tanstack/ai @tanstack/ai-effect @tanstack/ai-openai @tanstack/ai-react effect

Note that @tanstack/ai-effect declares zero runtime dependencies — effect and @tanstack/ai are peer dependencies, so your lockfile controls the versions.

Install cost, measured from the npm registry (unpacked sizes, current latest versions):

PackageUnpacked sizeFiles
@tanstack/ai-effect 0.1.061.4 kB18
@tanstack/ai 1.2.05737.3 kB644
@tanstack/ai-openai 1.1.1989.9 kB182
@tanstack/ai-react 1.0.2491.0 kB99
effect 4.1.255264.1 kB3013

The adapter itself is the smallest package in the set at 61.4 kB across 18 files. effect is the heavy peer at 55264.1 kB unpacked, but tree-shaking and server-only bundling keep it out of the client bundle entirely — the official client example ships plain React with useChat.

Stream a chat from your Effect server route

The official integration is three steps: first, install the packages; then, stream the chat from your server route; finally, show the chat on the client. The official docs' server example is small enough to reproduce in full:

ts
import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
import * as AI from '@tanstack/ai-effect'
import { openaiText } from '@tanstack/ai-openai'
import { Stream } from 'effect'

export async function POST(request: Request) {
  const params = await chatParamsFromRequest(request)

  const stream = AI.chat({
    adapter: openaiText('gpt-6.1-sol'),
    messages: params.messages,
    threadId: params.threadId,
    runId: params.runId,
  })

  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
}

Three pieces, each with a job:

  • AI.chat takes the same options as core chat() — same adapters, same messages, same thread/run IDs. It returns Stream<StreamChunk, AIError>.
  • Stream.toAsyncIterable converts the Effect Stream back into the async iterable that toServerSentEventsResponse reads, so the SSE transport layer stays unchanged.
  • Interruption is wired: browser closes the request → stream stops → model request aborted.

Show the chat on the client — no Effect required

The client stays plain React. useChat from @tanstack/ai-react reads the Server-Sent Events:

tsx
import { useState } from 'react'
import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'

export function Chat() {
  const [input, setInput] = useState('')
  const { messages, sendMessage, isLoading } = useChat({
    connection: fetchServerSentEvents('/api/chat'),
    threadId: 'effect-chat',
  })

  return (
    <div>
      {messages.map((message) => (
        <p key={message.id}>
          {message.role}: {message.parts.map((part) =>
            part.type === 'text' ? part.content : null)}
        </p>
      ))}
      <form onSubmit={(event) => { event.preventDefault(); sendMessage(input); setInput('') }}>
        <input value={input} onChange={(event) => setInput(event.target.value)} />
        <button type="submit" disabled={isLoading}>Send</button>
      </form>
    </div>
  )
}

The boundary is deliberate: Effect lives on the server, the client consumes plain SSE. You do not ship effect to the browser for a chat UI. Deployment-wise, the route uses Web-standard Request/Response, so it runs unchanged on Cloudflare Workers; in TanStack Start you can express the same handler as a Server Function if you prefer that shape.

Get the whole reply as an Effect

If you do not need token-by-token streaming, pass stream: false. AI.chat then returns an Effect of { text, chunks }, which composes with Effect.gen:

ts
import * as AI from '@tanstack/ai-effect'
import { openaiText } from '@tanstack/ai-openai'
import { Effect } from 'effect'

const program = Effect.gen(function* () {
  const { text } = yield* AI.chat({
    adapter: openaiText('gpt-6.1-sol'),
    messages: [{ role: 'user', content: 'Write a haiku about rivers.' }],
    threadId: 'haiku',
    stream: false,
  })
  return text
})

const haiku = await Effect.runPromise(program)

With outputSchema, the same call returns an Effect of the parsed structured object — same schema options as the core SDK's structured outputs.

What else ships in the adapter

The official docs list three more surfaces beyond AI.chat, all following the same "every activity as an Effect or Stream" rule:

  • Effect tools — give your AI tools Effect services, so tool execution inherits your dependency injection and error channels.
  • Effect activities — run images, embeddings, and speech as Effects.
  • Effect Chat tutorial — a full step-by-step app build in the official docs.

The decision framework: three questions before adopting

  1. Does your server import effect today? If yes, the adapter is strictly additive: same options as core chat(), typed into your existing error channel. If no, adding Effect just for AI calls is a runtime dependency you do not need; core chat() covers the same features.
  2. Do you need interruption correctness? Long agent loops with paid model calls leak money when a client disconnect leaves the provider request running. The adapter aborts upstream on downstream disconnect; hand-rolled async iterables require you to wire that yourself.
  3. Is your client React? The official client contract is useChat plus SSE from @tanstack/ai-react. Non-React clients consume the same SSE stream, but you will re-implement the hook.

Before and after: what changes in your code

The diff on a standard TanStack Start server route, using the official examples as the baseline:

AspectCore chat() (before)AI.chat (after)
Return typeAsyncIterable<StreamChunk>Stream<StreamChunk, AIError>
Errorsthrown plain Error, caught genericallytyped AIError in the channel
Client disconnectrequest continues unless you wire itaborts the model request
Composabilitymanual async-iterable combinatorsStream module combinators
Route shapeSSE route via toServerSentEventsResponseidentical

The route shape does not change, and that is the point: what changes is the type of the value flowing through it.

Methodology and limitations

Everything here is sourced from the official Effect documentation page, the published npm metadata for 0.1.0, and the GitHub repository, each linked above. I have not yet run this adapter in production; the before/after table compares documented contracts, not measured latency. Limitations to weigh: the package is 0.1.0, days old, pre-1.0, and its API can change; the docs cover React on the client, so non-React clients are undocumented territory; and adopting Effect 4 itself is a team-level commitment this article does not evaluate. The main caveat for tool-heavy agents: the docs list Effect tools and Effect activities as supported surfaces, but at 0.1.0 you should verify each tool pattern you rely on against the official Effect Chat tutorial before betting a production release on it.

Version and compatibility facts

PackageVersionNote
@tanstack/ai-effect0.1.0Published 2026-11-06; zero runtime deps
effect≥ 4.1.0 (peer)Effect 4 required
@tanstack/ai≥ 1.2.0 (peer)Current stable is 1.2.0
@tanstack/ai-openai—Provider adapter used in docs
@tanstack/ai-react—Client useChat / SSE transport

Status today: 0.1.0, days old, API subject to change before 1.0. The docs already cover it as a first-class surface, which is the signal that this is not an experiment — the docs site gained a whole Effect section, an Effect Chat tutorial, and Effect examples on the same day the package published.

When you should (and should not) adopt it

Adopt it when: your server is already Effect 4 — the adapter removes the impedance mismatch instead of making you wrap chat() by hand; you need typed AIError in your error channel instead of thrown errors; interruption correctness matters (long-running agent loops where leaked provider requests cost real money).

Skip it when: your server is plain TypeScript without Effect — core chat() already gives you the async iterable and SSE transport with fewer moving parts; or your client is non-React and you only need the SSE contract, which the adapter does not change.

For a SaaS built on TanStack Start, the interesting middle ground is server-side agents: tool-calling loops in Effect with retries typed into the channel, exposed to a React client through the same useChat contract as every other TanStack AI app.

FAQ

Does the client need Effect too?

No. The official example client is plain React with useChat reading Server-Sent Events. The Effect runtime stays on the server.

What Effect version is required?

Effect 4 — specifically effect 4.1.0 or later, declared as a peer dependency alongside @tanstack/ai 1.2.0+.

Does interruption actually cancel the model request?

Yes, per the official docs: when the browser closes the request the stream stops, and AI.chat then aborts the request to the model.

Can I get a single parsed object instead of a stream?

Yes. Pass stream: false to get an Effect of { text, chunks }, or use outputSchema to get an Effect of the parsed structured output.

Is 0.1.0 production-ready?

It is days old and pre-1.0, but it is documented as a first-class surface (own docs section, tutorial, examples) rather than an experimental add-on. Pin your versions and read the changelog before upgrading.

Further reading