Dashboard

TanStack AI 1.0 Migration: What Actually Breaks

The codemod renames two fields and the type check goes green. The thread identifier and your stored conversations are what break after that.

Carlo Zuercher
Carlo Zuercher
Staff Engineer, Platform
29 October 20261 min read

A TanStack AI 1.0 migration is mostly a codemod and a type check, and that is the trap. The codemod renames what it can see, the type checker goes green, and two things it cannot touch break in production: the thread identifier it is not able to invent, and the chat and run data already sitting in your database.

TanStack published 1.0 on 23 October 2026. Here is the upgrade in the order that avoids a broken deploy.

Before you start: everything moves together

A 1.0 client requires a 1.0 server. There is no mixed mode. Move every stable @tanstack/ai* package in one change, client and server, or the two sides will disagree about the event protocol.

Two exceptions worth knowing. The harness packages, @tanstack/ai-harness, @tanstack/ai-harness-cli and the harness entry points in other packages, stay on 0.x and remain experimental. And the three standalone UI packages are gone: @tanstack/ai-react-ui, @tanstack/ai-solid-ui and @tanstack/ai-vue-ui have no 1.0 release at all. If you depend on them, remove them and rebuild that surface with createChatHook from @tanstack/ai-react/ui, @tanstack/ai-solid/ui or @tanstack/ai-vue/ui.

That last one is a real piece of work, not a rename. Scope it before you begin rather than discovering it halfway through.

Step one: run the codemod

bash
npx jscodeshift --parser=tsx \
  -t https://raw.githubusercontent.com/TanStack/ai/main/codemods/ag-ui-compliance/transform.ts \
  "src/**/*.{ts,tsx}"

It handles two renames across your codebase: body becomes forwardedProps, and conversationId becomes threadId. Commit that on its own, before you touch anything by hand, so the mechanical change stays separable from your judgement calls.

Where a TanStack AI 1.0 migration goes wrong

This is where a TanStack AI 1.0 migration actually goes wrong.

  1. threadId is now required on both client and server. The codemod renames the field but cannot supply a value, because it has no idea where your identifiers come from. You pass it manually. Every call site that previously relied on the library defaulting a conversation identifier now needs a real one, and you have to decide whether it comes from your route, your session, or a row you create up front.

  2. addToolApprovalResponse() is removed. Instead of calling it, you resolve the tool-approval interrupt. If your product has a human-in-the-loop approval step, this is the code path that changes shape, not just name.

  3. Servers should end a run with a RUN_FINISHED event. The old practice of sending [DONE] is out. If you wrote your own streaming endpoint rather than using the provided server helpers, this is yours to change, and a client waiting for a terminator it never receives looks exactly like a hung request.

Step three: the deploy that passes types and still breaks

TanStack says it plainly in the release post, and it is the sentence to take seriously: passing the type checker does not migrate saved chats, runs, or files. Those rows were written in the 0.x shape. A green build tells you your source compiles, not that yesterday's conversations will load.

So before you deploy, work the saved-data steps in the official v1 migration guide against a copy of production data, and open an old thread in the new client. If your app lets people return to a conversation from last week, that is the regression your test suite will not catch.

A sane order of operations

  1. Read the release post and the migration guide end to end before editing anything.

  2. Audit for the three dropped UI packages. If you use them, scope that work separately.

  3. Bump every stable @tanstack/ai* package together. Leave the harness packages on 0.x.

  4. Run the codemod. Commit alone.

  5. Fix the type errors, which is where threadId surfaces.

  6. Replace the tool-approval calls and the stream terminator.

  7. Restore a production snapshot and load an old thread.

  8. Deploy client and server together.

Handing the mechanical middle of that list to an agent is reasonable; the method is in handing a large code migration to an AI coding agent. Steps one, two and seven are judgement, and an agent will cheerfully skip seven.

Why a 1.0 means more churn than it sounds

A 1.0 is a promise about what will not change next, which means it is also the last chance to delete things. TanStack removed every API that 0.x had marked deprecated, and the replacements all shipped during 0.x. If you kept up with deprecation warnings, this is small. If you ignored them for a year, 1.0 is where that bill arrives, which is the general argument for letting an agent keep your dependencies current rather than batching upgrades.

The version number itself is doing real work here, in the sense described in semantic versioning: a major release is the one that is allowed to break you. Also worth noting that the stable core and the experimental harness now move on separate tracks, which is the kind of distinction that matters when you choose what to build on. If the client and server split in this release is new to you, the difference between an SDK and an API is the background.

TanStack's announcement is on the TanStack blog. For the wider landscape these libraries sit in, see our overview of AI coding tools.

Frequently asked questions

Can I upgrade the client first and the server later?

No. A 1.0 client expects a 1.0 server. Ship them together, which in practice means one deploy or a brief maintenance window rather than a staged rollout.

Does the codemod handle everything?

It handles the body and conversationId renames. It cannot add threadId values, cannot rewrite tool-approval logic, and does not touch stored data. Budget manual time for those three.

What happens to my existing conversations?

They are not migrated by the upgrade. The release post is explicit that saved chats, runs and files need the separate steps in the migration guide. Test with real data before deploying.

Should I move to the harness APIs at the same time?

Not unless you have a reason to. They stay on 0.x and are marked experimental, so adopting them during a stability upgrade mixes a safe change with an unsafe one.

How did this land?

About the author

Carlo Zuercher
Carlo Zuercher

Staff Engineer, Platform

Carlo works on the platform that turns prompts into running apps. He writes the engineering deep dives and the changelog notes worth reading.

Share

Get the next post in your inbox

One email a month. Product updates, engineering posts, and the best of Built with Swarmz.

I agree to receive emails about AI building tips and Swarmz product news. Unsubscribe any time.