How to Integrate OpenAI in Next.js

Next.js gives you React for the UI and server-side Route Handlers for backend logic in one repo. That split is a good fit for OpenAI: the browser renders components, the server holds secrets and talks to the model.

Common use cases include customer support chat, summarizing long documents, generating draft copy, classifying support tickets, and powering internal tools. Each one follows the same shape: collect input on the client, send it to your API route, call OpenAI, return text or structured data.

You need a Next.js project using the App Router (the app/ directory), Node.js 18 or later, and an OpenAI account with an API key from the OpenAI dashboard. Create a new project with create-next-app if you are starting fresh.

This guide uses the official openai npm package (v6+) and the Responses API, which is the current recommended path for text generation and streaming in the Node SDK.

Add the package to your project. You only need this one dependency for server-side calls; do not install a separate client SDK for the browser.

npm install openai

Create a .env.local file at the project root. Next.js loads it automatically in development and expects the same variable names in production hosting (Vercel, Docker, etc.).

Prefixing is not required for server-only variables. Do not use NEXT_PUBLIC_ for the API key, because that prefix exposes values to the client bundle.

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o-mini

Instantiate OpenAI once and reuse it. Creating a new client on every request adds overhead. A small helper module also centralizes the check for a missing API key.

Place this file under lib/ or app/api/_lib/. Import it only from Route Handlers, Server Actions, or other server modules, never from Client Components.

import OpenAI from "openai";

let client: OpenAI | null = null;

export function getOpenAIClient(): OpenAI | null {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) return null;
  if (!client) {
    client = new OpenAI({ apiKey });
  }
  return client;
}

export function getChatModel(): string {
  return process.env.OPENAI_MODEL ?? "gpt-4o-mini";
}

Add a POST handler at app/api/chat/route.ts. It reads JSON from the request body, calls OpenAI, and returns the model output. Start with a non-streaming version to confirm the wiring, then add streaming in the next section.

Always validate the body shape before calling the API. Reject empty messages and cap string length so callers cannot send huge payloads.

import { getOpenAIClient, getChatModel } from "@/lib/openai-client";

export async function POST(request: Request) {
  const openai = getOpenAIClient();
  if (!openai) {
    return Response.json(
      { error: "OpenAI is not configured. Add OPENAI_API_KEY." },
      { status: 503 },
    );
  }

  const body = await request.json();
  const message = typeof body.message === "string" ? body.message.trim() : "";
  if (!message || message.length > 4000) {
    return Response.json({ error: "Invalid message." }, { status: 400 });
  }

  const response = await openai.responses.create({
    model: getChatModel(),
    input: message,
  });

  const text = response.output_text ?? "";
  return Response.json({ text });
}

For chat UIs, enable stream: true on responses.create and pipe text deltas into a ReadableStream. The client reads the stream with response.body.getReader() and updates the UI as chunks arrive.

Handle response.output_text.delta events in your stream loop. Close the stream when the model finishes or return a friendly error if the response fails.

import { getOpenAIClient, getChatModel } from "@/lib/openai-client";

function textDeltaStream(
  openaiStream: AsyncIterable<{ type: string; delta?: string }>,
): ReadableStream<Uint8Array> {
  const encoder = new TextEncoder();
  return new ReadableStream({
    async start(controller) {
      for await (const event of openaiStream) {
        if (event.type === "response.output_text.delta" && event.delta) {
          controller.enqueue(encoder.encode(event.delta));
        }
      }
      controller.close();
    },
  });
}

export async function POST(request: Request) {
  const openai = getOpenAIClient();
  if (!openai) {
    return new Response("OpenAI is not configured.", { status: 503 });
  }

  const { message } = await request.json();
  const stream = await openai.responses.create({
    model: getChatModel(),
    input: message,
    stream: true,
  });

  return new Response(textDeltaStream(stream), {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Mark your chat UI with "use client" and POST to /api/chat. For streaming, read the response body with a reader loop and append each decoded chunk to React state.

Disable the submit button while a request is in flight and show errors from non-OK responses so users know when the server or model failed.

"use client";

import { useState } from "react";

export function ChatBox() {
  const [input, setInput] = useState("");
  const [reply, setReply] = useState("");
  const [loading, setLoading] = useState(false);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setLoading(true);
    setReply("");

    const res = await fetch("/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ message: input }),
    });

    if (!res.ok || !res.body) {
      setReply("Something went wrong.");
      setLoading(false);
      return;
    }

    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let text = "";

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      text += decoder.decode(value, { stream: true });
      setReply(text);
    }

    setLoading(false);
  }

  return (
    <form onSubmit={handleSubmit}>
      <textarea value={input} onChange={(e) => setInput(e.target.value)} />
      <button type="submit" disabled={loading}>Send</button>
      <p>{reply}</p>
    </form>
  );
}

Keep the API key in server environment variables only. Audit imports so getOpenAIClient is never pulled into a Client Component.

Validate and sanitize all user input before sending it to OpenAI. Add per-IP or per-user rate limiting on the Route Handler so one client cannot abuse your endpoint.

Return generic error messages to the browser and log detailed errors on the server. Check request origin or CSRF tokens if the route is callable from browsers on other sites.

Pick a model that matches your quality and cost needs. Smaller models are fine for drafts and classification; use larger models only where accuracy matters.

Monitor token usage in the OpenAI dashboard and set billing alerts. Wrap OpenAI calls in try/catch and return 502 or 503 with a short message when the upstream API fails.

If AI is core to your product, plan for retries, timeouts, and fallbacks. Erratum Solutions can help harden streaming chat, lead capture, and multi-step flows for production traffic.