Open History to see the last commit
1---
2title: Migration Guide
3id: migration
4order: 1
5description: "Migrate existing TanStack AI code to the latest version — adapter function splits, flattened options, renamed modelOptions, and removed embeddings."
6keywords:
7 - tanstack ai
8 - migration
9 - upgrade
10 - breaking changes
11 - tree-shaking
12 - modelOptions
13 - toServerSentEventsStream
14---
15
16# Migration Guide
17
18This guide helps you migrate from the previous version of TanStack AI to the latest version. The major changes focus on improved tree-shaking, clearer API naming, and simplified configuration.
19
20## Overview of Changes
21
22The main breaking changes in this release are:
23
241. **Adapter functions split** - Adapters are now split into activity-specific functions for optimal tree-shaking
252. **Common options flattened** - Options are now flattened in the config instead of nested
263. **`providerOptions` renamed** - Now called `modelOptions` for clarity
274. **`toResponseStream` renamed** - Now called `toServerSentEventsStream` for clarity
285. **Embeddings removed** - Embeddings support has been removed (most vector DB services have built-in support)
29
30## 1. Adapter Functions Split
31
32Adapters have been split into activity-specific functions to enable optimal tree-shaking. Instead of importing a monolithic adapter, you now import specific functions for each activity type.
33
34### Before
35
36```typescript
37import { chat } from '@tanstack/ai'
38import { openai } from '@tanstack/ai-openai'
39
40const stream = chat({
41 adapter: openai(),
42 model: 'gpt-5.2',
43 messages: [{ role: 'user', content: 'Hello!' }],
44})
45```
46
47### After
48
49```typescript
50import { chat } from '@tanstack/ai'
51import { openaiText } from '@tanstack/ai-openai'
52
53const stream = chat({
54 adapter: openaiText('gpt-5.2'),
55 messages: [{ role: 'user', content: 'Hello!' }],
56})
57```
58
59### Key Changes
60
61- **Model is passed to adapter factory** - The model name is now passed directly to the adapter function (e.g., `openaiText('gpt-5.2')`)
62- **No separate `model` parameter** - The model is stored on the adapter, so you don't need to pass it separately to `chat()`
63- **Activity-specific imports** - Import only what you need (e.g., `openaiText`, `openaiSummarize`, `openaiImage`)
64
65### All Adapter Functions
66
67Each provider package now exports activity-specific functions:
68
69#### OpenAI
70
71```typescript
72import {
73 openaiText, // Chat/text generation
74 openaiSummarize, // Summarization
75 openaiImage, // Image generation
76 openaiSpeech, // Text-to-speech
77 openaiTranscription, // Audio transcription
78 openaiVideo, // Video generation
79} from '@tanstack/ai-openai'
80```
81
82#### Anthropic
83
84```typescript
85import {
86 anthropicText, // Chat/text generation
87 anthropicSummarize, // Summarization
88} from '@tanstack/ai-anthropic'
89```
90
91#### Gemini
92
93```typescript
94import {
95 geminiText, // Chat/text generation
96 geminiSummarize, // Summarization
97 geminiImage, // Image generation
98 geminiSpeech, // Text-to-speech (experimental)
99} from '@tanstack/ai-gemini'
100```
101
102#### Ollama
103
104```typescript
105import {
106 ollamaText, // Chat/text generation
107 ollamaSummarize, // Summarization
108} from '@tanstack/ai-ollama'
109```
110
111### Migration Example
112
113Here's a complete example of migrating adapter usage:
114
115#### Before
116
117```typescript
118import { chat } from '@tanstack/ai'
119import { openai } from '@tanstack/ai-openai'
120import { anthropic } from '@tanstack/ai-anthropic'
121
122type Provider = 'openai' | 'anthropic'
123
124function getAdapter(provider: Provider) {
125 switch (provider) {
126 case 'openai':
127 return openai()
128 case 'anthropic':
129 return anthropic()
130 }
131}
132
133const stream = chat({
134 adapter: getAdapter(provider),
135 model: provider === 'openai' ? 'gpt-5.2' : 'claude-sonnet-4-5',
136 messages,
137})
138```
139
140#### After
141
142```typescript
143import { chat } from '@tanstack/ai'
144import { openaiText } from '@tanstack/ai-openai'
145import { anthropicText } from '@tanstack/ai-anthropic'
146
147type Provider = 'openai' | 'anthropic'
148
149const adapters = {
150 openai: () => openaiText('gpt-5.2'),
151 anthropic: () => anthropicText('claude-sonnet-4-5'),
152}
153
154const stream = chat({
155 adapter: adapters[provider](),
156 messages,
157})
158```
159
160## 2. Common Options Flattened
161
162Common options that were previously nested in an `options` object are now flattened directly in the config.
163
164### Before
165
166```typescript
167const stream = chat({
168 adapter: openai(),
169 model: 'gpt-5.2',
170 messages,
171 options: {
172 temperature: 0.7,
173 maxTokens: 1000,
174 topP: 0.9,
175 },
176})
177```
178
179### After
180
181```typescript
182const stream = chat({
183 adapter: openaiText('gpt-5.2'),
184 messages,
185 temperature: 0.7,
186 maxTokens: 1000,
187 topP: 0.9,
188})
189```
190
191### Available Options
192
193These options are now available at the top level:
194
195- `temperature` - Controls randomness (0.0 to 2.0)
196- `topP` - Nucleus sampling parameter
197- `maxTokens` - Maximum tokens to generate
198- `metadata` - Additional metadata to attach
199
200## 3. `providerOptions` → `modelOptions`
201
202The `providerOptions` parameter has been renamed to `modelOptions` for clarity. This parameter contains model-specific options that vary by provider and model.
203
204### Before
205
206```typescript
207const stream = chat({
208 adapter: openai(),
209 model: 'gpt-5.2',
210 messages,
211 providerOptions: {
212 // OpenAI-specific options
213 responseFormat: { type: 'json_object' },
214 logitBias: { '123': 1.0 },
215 },
216})
217```
218
219### After
220
221```typescript
222const stream = chat({
223 adapter: openaiText('gpt-5.2'),
224 messages,
225 modelOptions: {
226 // OpenAI-specific options
227 responseFormat: { type: 'json_object' },
228 logitBias: { '123': 1.0 },
229 },
230})
231```
232
233### Type Safety
234
235`modelOptions` is fully typed based on the adapter and model you're using:
236
237```typescript
238import { openaiText } from '@tanstack/ai-openai'
239
240const adapter = openaiText('gpt-5.2')
241
242// TypeScript knows the exact modelOptions type for gpt-5.2
243const stream = chat({
244 adapter,
245 messages,
246 modelOptions: {
247 // Autocomplete and type checking for gpt-5.2 options
248 responseFormat: { type: 'json_object' },
249 },
250})
251```
252
253## 4. `toResponseStream` → `toServerSentEventsStream`
254
255The `toResponseStream` function has been renamed to `toServerSentEventsStream` to better reflect its purpose. Additionally, the API has changed slightly.
256
257### Before
258
259```typescript
260import { chat, toResponseStream } from '@tanstack/ai'
261import { openai } from '@tanstack/ai-openai'
262
263export async function POST(request: Request) {
264 const { messages } = await request.json()
265 const abortController = new AbortController()
266
267 const stream = chat({
268 adapter: openai(),
269 model: 'gpt-5.2',
270 messages,
271 abortController,
272 })
273
274 return toResponseStream(stream, { abortController })
275}
276```
277
278### After
279
280```typescript
281import { chat, toServerSentEventsStream } from '@tanstack/ai'
282import { openaiText } from '@tanstack/ai-openai'
283
284export async function POST(request: Request) {
285 const { messages } = await request.json()
286 const abortController = new AbortController()
287
288 const stream = chat({
289 adapter: openaiText('gpt-5.2'),
290 messages,
291 abortController,
292 })
293
294 const readableStream = toServerSentEventsStream(stream, abortController)
295 return new Response(readableStream, {
296 headers: {
297 'Content-Type': 'text/event-stream',
298 'Cache-Control': 'no-cache',
299 Connection: 'keep-alive',
300 },
301 })
302}
303```
304
305### Key Changes
306
307- **Function renamed** - `toResponseStream` → `toServerSentEventsStream`
308- **Returns ReadableStream** - Now returns a `ReadableStream` instead of a `Response`
309- **Manual Response creation** - You create the `Response` object yourself with appropriate headers
310- **AbortController parameter** - Passed as a separate parameter instead of in options
311
312### Alternative: HTTP Stream Format
313
314If you need HTTP stream format (newline-delimited JSON) instead of SSE, use `toHttpStream`:
315
316```typescript
317import { toHttpStream } from '@tanstack/ai'
318
319const readableStream = toHttpStream(stream, abortController)
320return new Response(readableStream, {
321 headers: {
322 'Content-Type': 'application/x-ndjson',
323 },
324})
325```
326
327## 5. Embeddings Removed
328
329Embeddings support has been removed from TanStack AI. Most vector database services (like Pinecone, Weaviate, Qdrant, etc.) have built-in support for embeddings, and most applications pick an embedding model and stick with it.
330
331### Before
332
333```typescript
334import { embedding } from '@tanstack/ai'
335import { openaiEmbed } from '@tanstack/ai-openai'
336
337const result = await embedding({
338 adapter: openaiEmbed(),
339 model: 'text-embedding-3-small',
340 input: 'Hello, world!',
341})
342```
343
344### After
345
346Use your vector database service's built-in embedding support, or call the provider's API directly:
347
348```typescript
349// Example with OpenAI SDK directly
350import OpenAI from 'openai'
351
352const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
353
354const result = await openai.embeddings.create({
355 model: 'text-embedding-3-small',
356 input: 'Hello, world!',
357})
358```
359
360### Why This Change?
361
362- **Vector DB services handle it** - Most vector databases have native embedding support
363- **Simpler API** - Reduces API surface area and complexity
364- **Direct provider access** - You can use the provider SDK directly for embeddings
365- **Focused scope** - TanStack AI focuses on chat, tools, and agentic workflows
366
367## 6. Provider Tools Moved to `/tools` Subpath
368
369Provider-specific tools (web search, code execution, computer use, etc.) are now
370exported from a dedicated `/tools` subpath on every adapter package. This keeps
371tool imports tree-shakeable and avoids name collisions between providers.
372
373The only breaking change is in `@tanstack/ai-openrouter`:
374`createWebSearchTool` has been removed from the package root, renamed to
375`webSearchTool`, and moved to `@tanstack/ai-openrouter/tools`. Every other
376provider tool (Anthropic, OpenAI, Gemini) is newly exported — no existing
377import breaks.
378
379### Before
380
381```typescript
382import { createWebSearchTool } from '@tanstack/ai-openrouter'
383
384const tools = [
385 createWebSearchTool({ engine: 'native', maxResults: 5 }),
386]
387```
388
389### After
390
391```typescript
392import { webSearchTool } from '@tanstack/ai-openrouter/tools'
393
394const tools = [
395 webSearchTool({ engine: 'native', maxResults: 5 }),
396]
397```
398
399### Key Changes
400
401- **Import path is now `/tools`** — matches the existing `/adapters` subpath
402 pattern used elsewhere in each provider package.
403- **Factory renamed** — `createWebSearchTool` → `webSearchTool`. The `create*`
404 prefix has been dropped to align with every other provider
405 (`webSearchTool` in `@tanstack/ai-anthropic/tools`,
406 `@tanstack/ai-openai/tools`, etc.).
407- **Runtime behavior is unchanged** — the factory accepts the same config
408 object and returns a tool that works identically in `chat({ tools: [...] })`.
409- **Type-level gating is new** — if you pass a provider tool to a model that
410 doesn't support it (per the model's `supports.tools` array), you now get a
411 type error on the `tools` array. User-defined `toolDefinition()` tools are
412 unaffected.
413
414For the full list of available provider tools and which models support each
415one, see [Provider Tools](../tools/provider-tools.md).
416
417## Complete Migration Example
418
419Here's a complete example showing all the changes together:
420
421### Before
422
423```typescript
424import { chat, toResponseStream } from '@tanstack/ai'
425import { openai } from '@tanstack/ai-openai'
426
427export async function POST(request: Request) {
428 const { messages } = await request.json()
429 const abortController = new AbortController()
430
431 const stream = chat({
432 adapter: openai(),
433 model: 'gpt-5.2',
434 messages,
435 options: {
436 temperature: 0.7,
437 maxTokens: 1000,
438 },
439 providerOptions: {
440 responseFormat: { type: 'json_object' },
441 },
442 abortController,
443 })
444
445 return toResponseStream(stream, { abortController })
446}
447```
448
449### After
450
451```typescript
452import { chat, toServerSentEventsStream } from '@tanstack/ai'
453import { openaiText } from '@tanstack/ai-openai'
454
455export async function POST(request: Request) {
456 const { messages } = await request.json()
457 const abortController = new AbortController()
458
459 const stream = chat({
460 adapter: openaiText('gpt-5.2'),
461 messages,
462 temperature: 0.7,
463 maxTokens: 1000,
464 modelOptions: {
465 responseFormat: { type: 'json_object' },
466 },
467 abortController,
468 })
469
470 const readableStream = toServerSentEventsStream(stream, abortController)
471 return new Response(readableStream, {
472 headers: {
473 'Content-Type': 'text/event-stream',
474 'Cache-Control': 'no-cache',
475 Connection: 'keep-alive',
476 },
477 })
478}
479```
480
481## Benefits of These Changes
482
4831. **Better Tree-Shaking** - Import only what you need, resulting in smaller bundle sizes
4842. **Clearer API** - Function names clearly indicate their purpose
4853. **Type Safety** - Model-specific options are fully typed
4864. **Simpler Configuration** - Flattened options are easier to work with
4875. **Focused Scope** - Removed features that are better handled elsewhere
488
489## Need Help?
490
491If you encounter issues during migration:
492
4931. Check the [Tree-Shaking Guide](../advanced/tree-shaking) for details on the new adapter structure
4942. Review the [API Reference](../api/ai) for complete function signatures
4953. Look at the [examples](../getting-started/quick-start) for working code samples
496
497