How to Implement AI in Next.js with Vercel AI SDK and TanStack AI

🤖 Introduction: Why AI Matters in Modern Web Apps

If you've been following web development trends, you've noticed something fundamental has shifted: users now expect AI as a core feature of applications, not a bonus.

Consider these everyday expectations:

• Chat-like interfaces for instant answers

• Smart assistants that learn your preferences

• Forms that auto-fill and suggest completions

• Real-time recommendations that feel personalized

These aren't "nice-to-haves" anymore. They're baseline expectations.

The Good News for Next.js Developers

Next.js doesn't come with AI built in—and that's actually perfect. Here's why:

Instead of forcing one AI approach on everyone, Next.js provides the perfect environment to connect with any AI provider safely:

The actual AI intelligence comes from external providers like:

• OpenAI (GPT-4, ChatGPT)

• Anthropic (Claude)

• Google (Gemini)

• Mistral (MistralAI)

The SDKs (software development kits) are the bridge between your Next.js app and these AI services.

---

🎯 What You'll Learn in This Guide

This guide covers two modern approaches to building AI features in Next.js:

By the end, you'll understand:

• How to securely connect to AI providers

• How to build streaming chat interfaces

• How to handle real-time AI responses

• When to choose each SDK

• Real production patterns

---

🔐 Prerequisites: Setting Up Your AI Provider

Before you can use AI in your Next.js app, you need a provider account and an API key.

Step 1: Create an OpenAI Account

1. Go to platform.openai.com

2. Sign up or log in

3. Navigate to "API keys" in your account settings

4. Click "Create new secret key"

5. Copy the key (you won't see it again!)

Step 2: Add Your API Key to Next.js

Create or update your .env.local file (this file is never committed to Git):

OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx

Your .env.local file stays on your machine—GitHub won't see it.

Step 3: Understand Why This Is Safe

Here's the crucial part: This API key will only run on the server.

In Next.js:

• Route Handlers run on the server only (your key is safe)

• React components run in the browser (they can't access this environment variable)

This separation is built into Next.js by default. You never have to worry about accidentally exposing your API key to the browser.

Other AI Providers You Can Use

Each provider works the same way: get an API key, add it to .env.local, and you're ready to go.

---

🚀 Part 1: Vercel AI SDK—The Quick Path to AI Features

What Is Vercel AI SDK?

Vercel AI SDK is a purpose-built library for building AI features in Next.js. It's created by Vercel (the company behind Next.js), so it integrates perfectly.

Think of it as a high-level toolkit that handles the hard parts for you:

• Streaming AI responses automatically

• Managing message history

• Handling errors gracefully

• Type safety where it matters

When to Use Vercel AI SDK

✅ Good fit for:

• Chat applications

• Quick prototyping

• Simple AI features

• Small to medium projects

• When you want something working fast

❌ Not ideal for:

• Complex AI workflows

• Advanced tool calling

• Highly custom behavior

• When you need maximum control

Architecture: How It Works

Here's the mental model:

User → Browser (Client)
         ↓ sends message
Server (Route Handler)
         ↓ calls OpenAI API
OpenAI Service
         ↓ streams response
Server (Route Handler)
         ↓ streams back to client
Browser (Client) ← updates in real-time

Notice how the data flows: user → server → AI provider → server → back to user. The server is the middleman, keeping your API key safe.

Step 1: Install Vercel AI SDK

npm install ai @ai-sdk/openai

This gives you:

• ai - The main SDK with streaming utilities

• @ai-sdk/openai - The connector to OpenAI's models

Official Documentation: sdk.vercel.ai

Step 2: Create the Server Endpoint (Route Handler)

Create a new file: app/api/chat/route.ts

// This file runs ONLY on the server
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

export async function POST(req: Request) {
  // 1. Get the messages from the user's request
  const { messages } = await req.json();

  // 2. Check if API key exists
  if (!process.env.OPENAI_API_KEY) {
    return new Response("API key not configured", { status: 500 });
  }

  try {
    // 3. Call the OpenAI API with streaming enabled
    const result = await streamText({
      model: openai("gpt-4o-mini"),  // The AI model to use
      messages,                       // Conversation history
    });

    // 4. Convert the stream to a format browsers understand
    return result.toDataStreamResponse();
  } catch (error) {
    return new Response("Error processing request", { status: 500 });
  }
}

What This Code Does

Why Streaming Matters

Without streaming:

User: "Write a poem"
[waiting 5 seconds]
AI: (suddenly returns entire poem)

With streaming:

User: "Write a poem"
[instantly starts appearing]
Line 1 appears...
Line 2 appears...
Line 3 appears...

Streaming feels 10x faster to users, even if the total time is the same.

Step 3: Create the Client Component

Create a new file: app/page.tsx

'use client';

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

export default function Chat() {
  // State for the input field
  const [input, setInput] = useState('');

  // Hook that manages the chat
  const { messages, sendMessage } = useChat();

  // Handle form submission
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (!input.trim()) return;

    sendMessage({ text: input });
    setInput('');
  };

  return (
    <div className="flex flex-col w-full max-w-2xl mx-auto h-screen">
      {/* Messages Display Area */}
      <div className="flex-1 overflow-y-auto p-4 space-y-4">
        {messages.map(message => (
          <div
            key={message.id}
            className={`p-3 rounded-lg ${
              message.role === 'user'
                ? 'bg-blue-100 text-blue-900 ml-12'
                : 'bg-gray-100 text-gray-900 mr-12'
            }`}
          >
            <div className="font-semibold text-sm mb-1">
              {message.role === 'user' ? 'You' : 'AI Assistant'}
            </div>

            {message.parts.map((part, i) => {
              // Handle different types of content
              if (part.type === 'text') {
                return <div key={`${message.id}-${i}`}>{part.text}</div>;
              }
              return null;
            })}
          </div>
        ))}
      </div>

      {/* Input Form */}
      <form
        onSubmit={handleSubmit}
        className="p-4 border-t border-gray-200 bg-white"
      >
        <div className="flex gap-2">
          <input
            type="text"
            value={input}
            onChange={e => setInput(e.currentTarget.value)}
            placeholder="Ask me anything..."
            className="flex-1 px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500"
          />
          <button
            type="submit"
            disabled={!input.trim()}
            className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed"
          >
            Send
          </button>
        </div>
      </form>
    </div>
  );
}

Breaking Down the Client Code

The useChat Hook:

• Automatically handles message state

• Manages conversation history

• Sends messages to /api/chat

• Displays responses as they stream in

Key Features:

• Messages are stored in order

• User messages appear in blue

• AI responses appear in gray

• Input clears after sending

• Submit button disables if input is empty

Step 4: Test Your Chat App

npm run dev

Visit http://localhost:3000 and start chatting with the AI!

---

🔧 Part 2: TanStack AI—The Production-Grade Approach

What Is TanStack AI?

TanStack AI is a different philosophy. Instead of "here's a complete solution," it's "here are powerful primitives—build what you need."

If Vercel AI SDK is like a pre-made cake, TanStack AI is like flour, eggs, and chocolate. You have more work, but you get exactly what you want.

When to Use TanStack AI

✅ Good fit for:

• Production applications

• Complex AI workflows

• Custom behavior requirements

• Type safety across AI logic

• Advanced features like tool calling

• Large teams needing consistency

❌ Not ideal for:

• Quick prototypes

• Simple chat interfaces

• When you want something working in 5 minutes

Key Differences from Vercel AI SDK

Step 1: Install TanStack AI

npm install @tanstack/ai @tanstack/ai-openai @tanstack/ai-react

This installs:

• @tanstack/ai - Core AI logic

• @tanstack/ai-openai - OpenAI connector

• @tanstack/ai-react - React hooks for the client

Official Documentation: @tanstack/ai Docs

Step 2: Create the Server Endpoint (Route Handler)

Create app/api/chat/route.ts:

// This file runs ONLY on the server
import { chat, toStreamResponse } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

export async function POST(request: Request) {
  // 1. Validate that API key exists
  if (!process.env.OPENAI_API_KEY) {
    return new Response(
      JSON.stringify({
        error: "OPENAI_API_KEY not configured",
      }),
      {
        status: 500,
        headers: { "Content-Type": "application/json" },
      }
    );
  }

  try {
    // 2. Parse the incoming request
    const { messages, conversationId } = await request.json();

    // 3. Create a streaming chat response
    const stream = chat({
      adapter: openaiText("gpt-4o"),    // Which AI model to use
      messages,                         // Conversation history
      conversationId,                   // Track conversation ID
    });

    // 4. Convert to HTTP streaming response
    return toStreamResponse(stream);
  } catch (error) {
    console.error("Chat API error:", error);
    return new Response(
      JSON.stringify({
        error: error instanceof Error ? error.message : "Unknown error",
      }),
      {
        status: 500,
        headers: { "Content-Type": "application/json" },
      }
    );
  }
}

Key Differences from Vercel SDK

1. Error Handling - More explicit error checking

2. Conversation ID - Tracks conversations for better management

3. Adapter Pattern - Uses openaiText() adapter instead of direct model reference

4. Type Safety - Every parameter is fully typed by TypeScript

Step 3: Create the Client Component

Create components/Chat.tsx:

'use client';

import { useState } from "react";
import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

export function Chat() {
  // State for input field
  const [input, setInput] = useState("");

  // TanStack's chat hook with streaming connection
  const { messages, sendMessage, isLoading } = useChat({
    // Connect to our server endpoint
    connection: fetchServerSentEvents("/api/chat"),
  });

  // Handle form submission
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

    // Don't send if input is empty or still loading
    if (!input.trim() || isLoading) return;

    sendMessage(input);
    setInput("");
  };

  return (
    <div className="flex flex-col h-screen bg-white">
      {/* Messages Container */}
      <div className="flex-1 overflow-y-auto p-4 space-y-4">
        {messages.map((message) => (
          <div key={message.id} className="mb-4">
            {/* Message Header */}
            <div className="font-semibold text-sm mb-2">
              {message.role === "assistant" ? "🤖 Assistant" : "👤 You"}
            </div>

            {/* Message Content */}
            <div className={`p-3 rounded-lg ${
              message.role === "assistant"
                ? "bg-gray-100 text-gray-900"
                : "bg-blue-100 text-blue-900 ml-12"
            }`}>
              {message.parts.map((part, idx) => {
                // Handle "thinking" parts (AI showing reasoning)
                if (part.type === "thinking") {
                  return (
                    <div
                      key={idx}
                      className="text-sm text-gray-500 italic mb-2 p-2 bg-gray-50 rounded"
                    >
                      💭 Thinking: {part.content}
                    </div>
                  );
                }

                // Handle regular text responses
                if (part.type === "text") {
                  return (
                    <div key={idx} className="whitespace-pre-wrap">
                      {part.content}
                    </div>
                  );
                }

                // Handle other part types if they exist
                return null;
              })}
            </div>
          </div>
        ))}

        {/* Loading Indicator */}
        {isLoading && (
          <div className="p-3 text-gray-500 italic">
            ⏳ AI is thinking...
          </div>
        )}
      </div>

      {/* Input Form */}
      <form onSubmit={handleSubmit} className="p-4 border-t border-gray-200 bg-white">
        <div className="flex gap-2">
          <input
            type="text"
            value={input}
            onChange={(e) => setInput(e.target.value)}
            placeholder="Type your message..."
            disabled={isLoading}
            className="flex-1 px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100"
          />
          <button
            type="submit"
            disabled={!input.trim() || isLoading}
            className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition"
          >
            {isLoading ? "..." : "Send"}
          </button>
        </div>
      </form>
    </div>
  );
}

Advanced Features in TanStack AI

1. "Thinking" Parts - Modern AI models like Claude can show their reasoning:

if (part.type === "thinking") {
  // Display the AI's internal thoughts
}

2. Loading State - Built-in loading indicator:

const { isLoading } = useChat();
// Disable inputs while waiting for response

3. Server-Sent Events - Handles streaming automatically:

connection: fetchServerSentEvents("/api/chat")
// Manages connection, retries, and backpressure

Step 4: Advanced Feature—Tool Calling

TanStack AI shines when you want the AI to call functions in your app. For example:

// Define what tools the AI can use
const tools = {
  getWeather: {
    description: "Get the current weather",
    parameters: {
      location: { type: "string", description: "City name" }
    },
    execute: async ({ location }) => {
      // Call your API
      const res = await fetch(`/api/weather?city=${location}`);
      return res.json();
    }
  }
};

// In your Route Handler
const stream = chat({
  adapter: openaiText("gpt-4o"),
  messages,
  tools,  // Pass the tools
});

Now the AI can:

1. Understand it has access to tools

2. Decide when to use them

3. Call them with appropriate parameters

4. Incorporate results into its response

This is powerful for:

• Real-time data fetching

• Database queries

• Form interactions

• External API calls

---

⚖️ Vercel AI SDK vs TanStack AI: Detailed Comparison

Feature Comparison Matrix

Decision Tree: Which Should You Use?

Start your project
    ↓
Is this a prototype/MVP?
    ├─ YES → Use Vercel AI SDK ✅
    └─ NO → Next question
              ↓
    Do you need advanced type safety?
        ├─ YES → Use TanStack AI ✅
        └─ NO → Do you need tool calling?
                  ├─ YES → Use TanStack AI ✅
                  └─ NO → Either works, pick Vercel for simplicity ✅

Example: When Each Wins

Vercel AI SDK Wins:

Build a simple chatbot in 15 minutes
"Requirement: Add basic chat to our SaaS product"
→ Vercel AI SDK gets it done fastest

TanStack AI Wins:

Build an AI agent that can book meetings
"Requirement: AI must fetch calendar, understand availability, send confirmations"
→ Tool calling in TanStack AI handles this elegantly

---

🔒 Security Best Practices: Keeping Your App Safe

Rule 1: Never Expose API Keys

❌ WRONG:

// On the client side - NEVER do this!
const response = await fetch("https://api.openai.com/v1/chat/completions", {
  headers: {
    "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`  // ❌ EXPOSED!
  }
});

✅ RIGHT:

// Send request to your server instead
const response = await fetch("/api/chat", {
  method: "POST",
  body: JSON.stringify({ messages })
});
// Your server has the API key, browser doesn't

Rule 2: Validate User Input

Always validate what users send before calling the AI:

// In your Route Handler
const { messages } = await request.json();

// Validate message structure
if (!Array.isArray(messages)) {
  return new Response("Invalid request", { status: 400 });
}

// Validate each message
messages.forEach(msg => {
  if (!msg.role || !msg.content) {
    return new Response("Invalid message", { status: 400 });
  }
});

Rule 3: Rate Limiting (Prevent Abuse)

// Pseudo-code: implement rate limiting
import { rateLimit } from "some-rate-limit-library";

export async function POST(req: Request) {
  const userId = getUserIdFromAuth(req);

  // Allow 100 requests per hour per user
  const { success } = await rateLimit(userId, {
    window: 3600,  // 1 hour in seconds
    limit: 100
  });

  if (!success) {
    return new Response("Too many requests", { status: 429 });
  }

  // Continue with chat...
}

Rule 4: Monitor Costs

AI API calls can get expensive quickly. Monitor usage:

// Log every request
export async function POST(req: Request) {
  const userId = getUserIdFromAuth(req);
  const startTime = Date.now();

  try {
    const result = await streamText({ /* ... */ });

    // Log successful request
    await logUsage({
      userId,
      timestamp: new Date(),
      model: "gpt-4o-mini",
      tokens: result.usage?.totalTokens || 0,
      cost: calculateCost(result.usage)
    });

    return result.toDataStreamResponse();
  } catch (error) {
    // Log errors too
    await logUsage({
      userId,
      error: error.message,
      timestamp: new Date(),
    });
    throw error;
  }
}

---

🏗️ Real-World Patterns: Building Production Features

Pattern 1: Chat with Persistent History

Store conversations in a database:

// In your Route Handler
export async function POST(req: Request) {
  const { messages, conversationId } = await req.json();
  const userId = getUserId(req);

  // Load existing conversation if it exists
  if (conversationId) {
    const stored = await db.conversations.findOne({
      _id: conversationId,
      userId
    });

    // Security: ensure user owns this conversation
    if (!stored) {
      return new Response("Unauthorized", { status: 403 });
    }
  }

  // Process AI response
  const result = await streamText({
    model: openai("gpt-4o"),
    messages,
  });

  // Optionally save to database
  // (You might do this after the response completes)

  return result.toDataStreamResponse();
}

Pattern 2: AI with Context Awareness

Pass relevant data to the AI:

// Fetch user context
const user = await db.users.findOne({ id: userId });
const recentPosts = await db.posts.find(
  { userId },
  { limit: 5, sort: { createdAt: -1 } }
);

// Build a system message with context
const systemMessage = `
You are an AI assistant for ${user.name}.
Their recent posts include:
${recentPosts.map(p => `- ${p.title}`).join('\n')}

Use this context to provide personalized responses.
`;

// Pass to AI
const result = await streamText({
  model: openai("gpt-4o"),
  system: systemMessage,
  messages,
});

Pattern 3: Streaming Responses to UI

Display streaming responses as they arrive:

'use client';

import { useEffect, useState } from 'react';

export function ChatWithStreaming() {
  const [streamingText, setStreamingText] = useState('');

  const handleSendMessage = async (message: string) => {
    const response = await fetch('/api/chat', {
      method: 'POST',
      body: JSON.stringify({ messages: [{ role: 'user', content: message }] })
    });

    // Read the stream line by line
    const reader = response.body?.getReader();
    const decoder = new TextDecoder();

    if (!reader) return;

    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        // Append chunk to displayed text
        setStreamingText(prev => prev + chunk);
      }
    } finally {
      reader.releaseLock();
    }
  };

  return (
    <div>
      <div className="p-4 bg-gray-100 rounded">{streamingText}</div>
      <button onClick={() => handleSendMessage('Hello')}>
        Send
      </button>
    </div>
  );
}

---

🚀 Getting Started: Step-by-Step Checklist

For Vercel AI SDK

• Install: npm install ai @ai-sdk/openai

• Create .env.local with OPENAI_API_KEY

• Create app/api/chat/route.ts (Route Handler)

• Create app/page.tsx (Chat Component)

• Test at http://localhost:3000

• Deploy to Vercel, Netlify, or your host

For TanStack AI

• Install: npm install @tanstack/ai @tanstack/ai-openai @tanstack/ai-react

• Create .env.local with OPENAI_API_KEY

• Create app/api/chat/route.ts (Route Handler)

• Create components/Chat.tsx (Chat Component)

• Create app/page.tsx to use Chat component

• Test at http://localhost:3000

• Deploy to Vercel, Netlify, or your host

Troubleshooting

---

📊 Comparison: Model Selection Guide

Different AI models have different strengths:

Recommendation: Start with gpt-4o-mini. It's fast, cheap, and high-quality. Upgrade to gpt-4o only if you need better reasoning.

---

📚 Learning Resources & Documentation

Official Documentation

Video Tutorials & Learning Resources

Community & Support

Recommended Learning Path

Week 1: Fundamentals

• Read OpenAI API Docs (1 hour)

• Watch Vercel AI SDK tutorial (30 minutes)

• Follow Getting Started checklist above

• Build basic chat app

Week 2: Deep Dive

• Study streaming concepts (1 hour)

• Watch advanced Next.js AI tutorial (1 hour)

• Implement persistent history

• Add error handling

Week 3: Production Patterns

• Read about tool calling (1 hour)

• Explore real-world examples on Cookbook (1 hour)

• Implement context-aware AI

• Add rate limiting and monitoring

Week 4: Advanced

• Study security best practices (1 hour)

• Explore TanStack AI for complex workflows

• Join Discord communities

• Build personal project

Code Examples & GitHub Repositories

Interactive Playgrounds

---

🎓 Conclusion: You're Ready to Build

Implementing AI in Next.js is no longer complex or mysterious. Here's what you now understand:

1. Architecture - How requests flow from browser → server → AI provider

2. Security - Why API keys stay on the server

3. Streaming - Why responses feel instant

4. SDKs - When to use Vercel AI SDK vs TanStack AI

5. Implementation - Real code you can copy and adapt

6. Patterns - Production-ready approaches

7. Resources - Where to find help and learn more

Whether you choose Vercel AI SDK for rapid prototyping or TanStack AI for production applications, you have the tools to build intelligent features that users will love.

Your Next Steps

1. Pick a provider (OpenAI, Claude, or Gemini)

2. Get an API key (5 minutes)

3. Choose your SDK (Vercel for speed, TanStack for control)

4. Build your first feature (copy-paste from this guide)

5. Deploy (Vercel makes this one-click)

6. Learn continuously (use resources above)

The hardest part is done. Now you're ready to build the AI-powered applications users expect.

---

📚 Glossary: Key Terms Explained

---

This comprehensive guide provides everything you need to integrate AI into your Next.js applications. Whether you're building a simple chatbot or complex AI agent, you now have the knowledge, code examples, and curated learning resources to do it securely and efficiently.

Happy building! 🚀