OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx

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

npm install ai @ai-sdk/openai

// 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 });
  }
}

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

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

'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>
  );
}

npm run dev

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

// 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" },
      }
    );
  }
}

'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>
  );
}

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

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

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

// 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
});

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 ✅

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

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

// 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!
  }
});

// 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

// 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 });
  }
});

// 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...
}

// 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;
  }
}

// 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();
}

// 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,
});

'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>
  );
}