tanstack-ai-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating to TanStack AI

迁移到 TanStack AI

Two different jobs. Pick the one that matches the code in front of you.

有两种不同的工作。选择与当前代码对应的一种。

Coming from another SDK

从其他 SDK 迁移

The name-by-name mapping lives in the docs, and it is longer than any summary that fits here:

https://tanstack.com/ai/latest/docs/migration/migration-from-vercel-ai

The shape of the change:

```
streamText
```
and
```
generateText
```
become one
```
chat()
```
call with a streaming option.

createOpenAI(...)

becomes a tree-shakeable adapter, such as

openaiText()

from

@tanstack/ai-openai

```
onFinish
```
and friends become middleware hooks.
Manual SSE wiring becomes the built-in response helpers.
```
generateObject
```
becomes structured outputs on
```
chat()
```
.

Read the guide, then load the target API's own skill with

npx @tanstack/intent@latest load @tanstack/ai#ai-core

. Do not port from memory: a half-remembered mapping produces code that type-checks in neither SDK.

逐个名称的映射写在文档中，比此处能容纳的任何摘要都更详细：

https://tanstack.com/ai/latest/docs/migration/migration-from-vercel-ai

变更形态如下：

```
streamText
```
和
```
generateText
```
合并为一次带 streaming option 的
```
chat()
```
调用。
```
createOpenAI(...)
```
变为可 tree-shake 的 adapter，例如来自
```
@tanstack/ai-openai
```
的
```
openaiText()
```
。
```
onFinish
```
等 API 变为 middleware hooks。
手动 SSE wiring 变为内置的 response helpers。
```
generateObject
```
变为
```
chat()
```
上的 structured outputs。

阅读指南后，通过以下命令加载目标 API 自身的 skill：

npx @tanstack/intent@latest load @tanstack/ai#ai-core

。不要凭记忆移植：只记住一部分映射会生成在两个 SDK 中都无法通过类型检查的代码。

Upgrading TanStack AI itself

升级 TanStack AI 本身

Start with the version the app has, and the current release:

bash

node -p "require('@tanstack/ai/package.json').version"
npm view @tanstack/ai version

Then read the guides for what changed:

Deprecated APIs keep working, so upgrade in steps rather than rewriting everything at once.

先确定应用当前使用的版本和最新发行版：

bash

node -p "require('@tanstack/ai/package.json').version"
npm view @tanstack/ai version

然后阅读变更指南：

已弃用的 API 仍可继续使用，因此应分步骤升级，而不是一次性重写所有代码。

Codemods

Some renames have a jscodeshift transform. Run it straight from the repo, and preview first with

--dry --print

bash

npx jscodeshift \
  -t https://raw.githubusercontent.com/TanStack/ai/main/codemods/ag-ui-compliance/transform.ts \
  --dry --print src/

Each guide names the codemod that covers it, and what the codemod cannot reach. Server-side rewrites are usually manual.

部分重命名已有 jscodeshift transform。可直接在 repo 中运行，并先用

--dry --print

预览：

bash

npx jscodeshift \
  -t https://raw.githubusercontent.com/TanStack/ai/main/codemods/ag-ui-compliance/transform.ts \
  --dry --print src/

每篇指南都会指明对应的 codemod，以及 codemod 无法处理的部分。服务端重写通常需要手动完成。

After the port

完成迁移后

Run the project's type checker. Most errors after a migration come from an API that was remembered rather than read, so check the failing name against

node_modules/@tanstack/ai/src/

before changing it again.

运行项目的 type checker。迁移后的大多数错误源于凭记忆而非阅读文档使用 API，因此在再次修改前，应对照

node_modules/@tanstack/ai/src/

检查出错的名称。