Stream Chat with Vercel AI SDK and Next.js

Updated 2 min read

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.

Watch the video on YouTube

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.

TerminalTested: all commands succeeded
# 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/react

Installing 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.

TerminalTested: all commands succeeded
# 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.

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

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.

TerminalTested: all commands succeeded
# 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.

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

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.

TerminalNot verified in our test run
# 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.

Sources

Subscribe for more tested tutorials