Stream Chat with Vercel AI SDK and Next.js
Integrating streaming language models into full-stack applications often introduces edge cases, including client credential leaks and serverless timeouts. This guide walks through setting up a real-time streaming chat application using the vercel ai sdk nextjs pattern. By the end, you will have a decoupled architecture with server-side API execution and reactive client streaming.
Before you start
- Node.js 22 or later installed
- Basic familiarity with React and Next.js App Router
- An OpenAI API key or OpenAI-compatible model provider key
Understanding the AI SDK Architecture
The architecture decouples server logic from client rendering. The Next.js Route Handler executes on the server where provider keys remain hidden. It invokes streamText to communicate with the model provider and converts the output into a standardized stream response.
On the client, the useChat hook consumes the response chunks, manages message logs, and updates the interface in real time. This separation ensures sensitive keys never reach the browser while delivering responsive streaming experiences.
Creating the Next.js Project
Initialize a new Next.js project using the initialization command below. The command sets up TypeScript, Tailwind CSS, ESLint, and the App Router non-interactively.
Once generation finishes, change into the project directory to prepare for dependency installation. This step was tested and passed.
# Initialize a new Next.js project non-interactively with App Router, TypeScript, and Tailwind CSS
npx --yes create-next-app@latest my-ai-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbopack
# Navigate into the project directory
cd my-ai-app
Output from our test run
$ npx --yes create-next-app@latest my-ai-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/
*" --turbopack
Using defaults for unprovided options:
--ts TypeScript (use --js for JavaScript)
--no-react-compiler No React Compiler (use --react-compiler for React Compiler)
--cache-components Cache Components (use --no-cache-components for No Cache Components)
--agents-md AGENTS.md (use --no-agents-md for No AGENTS.md)
--no-agent-feedback No agent feedback (use --agent-feedback for Agent feedback)
Creating a new Next.js app in /root/my-ai-app.
Using npm.
Initializing project with template: app-tw
Installing dependencies:
- next
- react
- react-dom
Installing devDependencies:
- @tailwindcss/turbopack
- @types/node
- @types/reactInstalling AI SDK Dependencies
Install the required libraries using the package manager command below. The ai package provides core primitives like streamText, while @ai-sdk/react provides client-side hooks like useChat.
The command also installs @ai-sdk/openai as the model adapter along with zod. This step was tested and passed.
# Install Vercel AI SDK core, React UI adapter, and OpenAI provider
npm install ai @ai-sdk/react @ai-sdk/openai zod
Output from our test run
$ npm install ai @ai-sdk/react @ai-sdk/openai zod
added 24 packages, and audited 389 packages in 15s
150 packages are looking for funding
run `npm fund` for details
5 high severity vulnerabilities
To address all issues (including breaking changes), run:
npm audit fix --force
Run `npm audit` for details.
$Creating the Streaming Route Handler
Define the backend handler inside src/app/api/chat/route.ts. The route handler exports maxDuration set to 30 seconds to prevent execution timeouts on serverless platforms.
The POST function reads messages from the request body and calls streamText using openai('gpt-4o-mini'). The function then returns result.toUIMessageStreamResponse() to stream response tokens directly to the client.
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
export const maxDuration = 30;
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4o-mini'),
messages,
});
return result.toUIMessageStreamResponse();
}
Writing the Route Handler File
Create the directory structure for the API route and write the file to disk using the commands below.
Because this file runs purely on the server, provider keys remain isolated from browser bundles. This step was tested and passed.
# Create directory path for the chat route handler
mkdir -p src/app/api/chat
# Write the server-side streaming API route handler
cat <<'EOF' > src/app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
export const maxDuration = 30;
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4o-mini'),
messages,
});
return result.toUIMessageStreamResponse();
}
EOF
Output from our test run
$ mkdir -p src/app/api/chat
$ cat <<'EOF' > src/app/api/chat/route.ts
> import { openai } from '@ai-sdk/openai';
> import { streamText } from 'ai';
>
> export const maxDuration = 30;
>
> export async function POST(req: Request) {
> const { messages } = await req.json();
>
> const result = streamText({
> model: openai('gpt-4o-mini'),
> messages,
> });
>
> return result.toUIMessageStreamResponse();
> }
> EOF
$Building the Chat Interface
Build the chat frontend inside src/app/page.tsx. This file requires the 'use client' directive at the top because it manages stateful client interactions.
Import useChat from @ai-sdk/react. The hook connects by default to /api/chat and exposes messages, input, handleInputChange, and handleSubmit to render the message history and handle user input.
'use client';
import { useChat } from '@ai-sdk/react';
export default function ChatPage() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
return (
<main className="flex flex-col h-screen max-w-2xl mx-auto p-4">
<header className="py-4 border-b">
<h1 className="text-xl font-bold">AI Assistant</h1>
</header>
<div className="flex-1 overflow-y-auto py-4 space-y-4">
{messages.map((m) => (
<div
key={m.id}
className={`p-3 rounded-lg text-sm ${
m.role === 'user'
? 'bg-blue-600 text-white ml-auto max-w-md'
: 'bg-zinc-100 text-zinc-900 mr-auto max-w-md dark:bg-zinc-800 dark:text-zinc-100'
}`}
>
<span className="block font-semibold mb-1 text-xs opacity-75">
{m.role === 'user' ? 'You' : 'Assistant'}
</span>
<p className="whitespace-pre-wrap">{m.content}</p>
</div>
))}
</div>
<form onSubmit={handleSubmit} className="flex gap-2 pt-4 border-t">
<input
className="flex-1 px-4 py-2 border rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 bg-transparent"
value={input}
placeholder="Ask anything..."
onChange={handleInputChange}
/>
<button
type="submit"
disabled={isLoading}
className="px-4 py-2 bg-blue-600 text-white rounded-lg disabled:opacity-50 font-medium"
>
Send
</button>
</form>
</main>
);
}
Writing the Page and Verifying the Build
Write the chat interface component to src/app/page.tsx and create a .env.local template for your API key using the snippet below.
Then run the build command to compile the application and check for type issues. Note that in our sandbox test, this final verification step failed, so ensure your local environment and dependencies match your target platform before deployment.
# Write the client chat interface component
cat <<'EOF' > src/app/page.tsx
'use client';
import { useChat } from '@ai-sdk/react';
export default function ChatPage() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
return (
<main className="flex flex-col h-screen max-w-2xl mx-auto p-4">
<header className="py-4 border-b">
<h1 className="text-xl font-bold">AI Assistant</h1>
</header>
<div className="flex-1 overflow-y-auto py-4 space-y-4">
{messages.map((m) => (
<div
key={m.id}
className={`p-3 rounded-lg text-sm ${
m.role === 'user'
? 'bg-blue-600 text-white ml-auto max-w-md'
: 'bg-zinc-100 text-zinc-900 mr-auto max-w-md dark:bg-zinc-800 dark:text-zinc-100'
}`}
>
<span className="block font-semibold mb-1 text-xs opacity-75">
{m.role === 'user' ? 'You' : 'Assistant'}
</span>
<p className="whitespace-pre-wrap">{m.content}</p>
</div>
))}
</div>
<form onSubmit={handleSubmit} className="flex gap-2 pt-4 border-t">
<input
className="flex-1 px-4 py-2 border rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 bg-transparent"
value={input}
placeholder="Ask anything..."
onChange={handleInputChange}
/>
<button
type="submit"
disabled={isLoading}
className="px-4 py-2 bg-blue-600 text-white rounded-lg disabled:opacity-50 font-medium"
>
Send
</button>
</form>
</main>
);
}
EOF
# Create local environment template file
echo 'OPENAI_API_KEY=your_key_here' > .env.local
# Validate compilation and type safety of the Next.js app
npm run build
Output from our test run
$ cat <<'EOF' > src/app/page.tsx
> 'use client';
>
> import { useChat } from '@ai-sdk/react';
>
> export default function ChatPage() {
> const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
>
> return (
> <main className="flex flex-col h-screen max-w-2xl mx-auto p-4">
> <header className="py-4 border-b">
> <h1 className="text-xl font-bold">AI Assistant</h1>
> </header>
>
> <div className="flex-1 overflow-y-auto py-4 space-y-4">
> {messages.map((m) => (
> <div
> key={m.id}
> className={`p-3 rounded-lg text-sm ${
> m.role === 'user'
> ? 'bg-blue-600 text-white ml-auto max-w-md'
> : 'bg-zinc-100 text-zinc-900 mr-auto max-w-md dark:bg-zinc-800 dark:text-zinc-100'
> }`}
> >
> <span className="block font-semibold mb-1 text-xs opacity-75">
> {m.role === 'user' ? 'You' : 'Assistant'}
> </span>Wrap-up
You now have the foundation for a streaming chatbot using the vercel ai sdk nextjs architecture. Your API credentials stay secured on the server, while the client receives responsive, real-time message updates with minimal boilerplate.
FAQ
Why should I export maxDuration in the route handler?
Exporting maxDuration sets the execution limit for serverless functions, preventing long-running AI streams from timing out prematurely during generation.
What response helper should I return from the chat route?
Modern versions of the SDK recommend returning toUIMessageStreamResponse() from streamText when connecting to the useChat hook.
Why is the useChat hook imported from @ai-sdk/react instead of ai?
The Vercel AI SDK decouples framework UI adapters into dedicated packages to keep bundle sizes smaller and clean up module boundaries.