Next.js

Overview

Next.js is where most AI products end up, and the App Router's server/client split maps unusually well onto the problem — because the one thing that must never reach the browser is your API key.

This lesson is the request path through an App Router app: which parts render on the server, where the model call belongs, how a route handler returns a stream straight to the client, and how the runtime choice bites you on long generations.

Theory

Server Components are the default, deliberately. They run on the server, never ship to the browser, and can hold secrets. In an AI app that matters more than usual: your API key belongs in code the client never receives.

Client Components are for the parts that need interactivity. "use client" marks a boundary, not a whole page. The input box and the streaming message list need it. The layout around them does not, and pushing the boundary as deep as possible keeps the bundle small.

Route handlers are your AI backend. A route.ts is where the model call lives, where the key is read, and what returns the stream. If you find yourself wanting the key in a NEXT_PUBLIC_ variable, that is the signal you are calling from the wrong side.

Streaming is structural here, not a library trick. A route handler can return a Response whose body is a stream, and the framework forwards it. No polling, no websocket, no special client.

Runtime choice matters for long calls. Edge starts faster and is cheaper for short work but has stricter limits and a smaller API surface. Node handles longer generations and libraries that need real Node built-ins. Pick per route, not per project.

Visual Diagram

Read it left to right. The browser holds a Client Component ("use client") that captures user input and calls fetch("/api/chat"). That request lands on a Route Handler running on the server — the only place that holds the model provider's API key. The Route Handler calls the provider, gets back a token stream, and forwards that stream as the Response body. The browser reads the response body incrementally and updates the UI as bytes arrive, so the user sees words appear before the model has finished generating the full answer. At no point does the API key, or any server-only logic, cross into code the browser can inspect.

Examples

• A chat page where the message list and input box are a Client Component using useChat, but the surrounding layout (nav, sidebar, footer) stays a Server Component and never re-renders on the client.
• A Route Handler at app/api/chat/route.ts that proxies to a model provider (in this codebase, the Lovable AI Gateway via src/lib/ai-gateway.server.ts) and streams the response back.
• A loading skeleton shown via loading.tsx while the first token of a slow generation is still in flight, so the page never looks frozen even before streaming kicks in.
• A Suspense boundary around a single panel — for example a "related documents" RAG panel that takes longer than the rest of the page — so a slow retrieval step doesn't block an otherwise-instant page load.

Code

// app/api/chat/route.ts — the server-only endpoint that holds the API key.
import { streamText } from "ai";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

export const runtime = "nodejs"; // long-lived streaming needs the full Node runtime here

const provider = createOpenAICompatible({
  name: "lovable-ai-gateway",
  baseURL: "https://ai.gateway.lovable.dev/v1",
  headers: { "Lovable-API-Key": process.env.LOVABLE_API_KEY ?? "" },
});

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: provider("gpt-4o-mini"),
    system: "You are a concise, helpful assistant.",
    messages,
  });

  // Turns the token stream into a Response the browser can read
  // incrementally — no waiting for the full answer before anything renders.
  return result.toTextStreamResponse();
}

// app/chat/page.tsx — a Client Component; it needs local state and live
// updates as tokens arrive, which a Server Component cannot do on its own.
"use client";

import { useState } from "react";

export default function ChatPage() {
  const [input, setInput] = useState("");
  const [reply, setReply] = useState("");

  async function send() {
    setReply("");
    const res = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ messages: [{ role: "user", content: input }] }),
    });

    const reader = res.body!.getReader();
    const decoder = new TextDecoder();

    // Read the stream chunk by chunk and append to the UI as it arrives —
    // this is what makes a model response feel instant instead of frozen.
    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      setReply((prev) => prev + decoder.decode(value));
    }
  }

  return (
    <div>
      <input value={input} onChange={(e) => setInput(e.target.value)} />
      <button onClick={send}>Send</button>
      <p>{reply}</p>
    </div>
  );
}

Notice the boundary: LOVABLE_API_KEY is read only inside app/api/chat/route.ts, which never ships to the browser. ChatPage only ever talks to your own /api/chat endpoint over a normal fetch — it has no way to see the key even if you wanted it to. That separation is the entire reason Route Handlers exist for AI features.

Real Product Example

v0 by Vercel is a clean example of this architecture in production. A user describes a UI in natural language; that prompt is sent to a server-side endpoint, which calls a model with streamText and streams the response back token by token. The browser renders the generated code (and a live preview of it) incrementally as it streams in, rather than showing a spinner until the entire component is done generating — the same Response-body-as-a-stream pattern shown in the Code section above, just generating React/JSX instead of chat replies. The product's core "feel" — code appearing progressively while you watch — is a direct consequence of choosing a framework where server-to-client streaming is a first-class primitive instead of something bolted on with a polling loop.

Common Mistakes

Senior Tips

Exercises

Mini Project

Streaming echo endpoint. Before wiring up a real model, prove the streaming mechanics work end to end with something you fully control.

1. Build app/api/echo/route.ts: a POST handler that takes { text: string }, splits it into words, and streams them back one at a time with a short artificial delay between each — simulating token-by-token model output without spending a single real token.
2. Build a client page that sends text to /api/echo and renders the streamed words as they arrive, exactly like the chat page in the Code section.
3. Add a loading.tsx skeleton that shows before the first word arrives.
4. Add a "Stop" button wired to an AbortController that cancels the in-flight stream.

This gives you a fully working streaming UI you can swap a real model into later without changing the client code at all — only the Route Handler's internals change.

Resources

• Next.js — Route Handlers: the canonical reference for route.ts files, including the streaming example this lesson's Code section builds on.
• Vercel AI SDK — Next.js App Router Quickstart: a full walkthrough of wiring streamText/useChat into an App Router project, including tool calling.
• Next.js — loading.js (Streaming UI): how loading.tsx and Suspense boundaries stream a route's UI progressively instead of blocking on the slowest part.