Migration Guide

Migrate from standard AI SDK to our enhanced tools with minimal changes. Get better performance, global state access, and powerful debugging capabilities.

Quick Migration (30 seconds)

◇ One Line Change

Replace your import and everything else works exactly the same:

// Before
import { useChat } from '@ai-sdk/react'

// After - ONLY CHANGE NEEDED
import { useChat } from '@ai-sdk-tools/store'

Step by Step Migration

1. Install the package

npm install @ai-sdk-tools/store

2. Update your imports

// Replace this
import { useChat } from '@ai-sdk/react'

// With this
import { useChat } from '@ai-sdk-tools/store'

3. Create the store (optional)

For global state access, create a store instance:

// store.ts
import { createAIStore } from '@ai-sdk-tools/store'

export const store = createAIStore({
  initialMessages: [],
  onFinish: (message) => {
    console.log('Message finished:', message)
  },
})

4. Add DevTools (optional)

import { AIDevTools } from '@ai-sdk-tools/devtools'

function App() {
  return (
    <div>
      <AIDevTools />
      {/* Your app content */}
    </div>
  )
}

What You Get

🌍 Global State

Access chat state from any component without prop drilling.

⚡ Performance

Optimized re-renders with selective subscriptions.

🔧 DevTools

Powerful debugging and monitoring capabilities.

🔒 Type Safety

Full TypeScript support with auto-completion.

Common Migration Patterns

Before: Prop Drilling

// Before: Props everywhere
function App() {
  const { messages, input, handleSubmit } = useChat()
  
  return (
    <div>
      <Header messages={messages} />
      <Chat messages={messages} />
      <Input input={input} onSubmit={handleSubmit} />
    </div>
  )
}

After: Global Access

// After: No props needed
function App() {
  return (
    <div>
      <Header />
      <Chat />
      <Input />
    </div>
  )
}

function Header() {
  const { messages } = useChat() // Access anywhere
  return <div>{messages.length} messages</div>
}

Troubleshooting

Common Issues

State not updating

Make sure you're using the same store instance across components. Create a store and export it from a shared file.

DevTools not showing

Ensure the AIDevTools component is rendered in your app and check the browser console for any errors.

TypeScript errors

Make sure you have the latest version of @ai-sdk-tools/store and that your TypeScript configuration is up to date.

Examples

Live Demo

See the migration in action with our interactive demo.

Try it out →

GitHub

View source code and more examples on GitHub.

View on GitHub →