Integrating the Anthropic Claude API into a Next.js App

Anthropic's Claude API is one of the most capable LLM APIs available. This guide covers integrating it into a Next.js application — from basic completions to streaming, tool use, and prompt caching — using patterns I've applied in production AI products.

Installation and Basic Setup

Install the Anthropic SDK and add your API key to environment variables. Your API key must never be exposed to the browser — always call the Claude API from a Next.js Route Handler or Server Action. The SDK works in both Node.js and edge runtimes.

npm install @anthropic-ai/sdk

// app/api/chat/route.js
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

export async function POST(req) {
  const { message } = await req.json();
  const response = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: message }],
  });
  return Response.json({ text: response.content[0].text });
}

Streaming Responses

For conversational UI, streaming is essential. Users see output within milliseconds of submitting rather than waiting for the full response. The SDK's stream() method handles the SSE protocol and provides a clean async iterator over text chunks. Return a ReadableStream from your Route Handler and consume it on the client with the Fetch API.

// app/api/chat/route.js (streaming)
export async function POST(req) {
  const { messages } = await req.json();

  const stream = client.messages.stream({
    model: 'claude-sonnet-4-6',
    max_tokens: 2048,
    messages,
  });

  const readable = new ReadableStream({
    async start(controller) {
      for await (const chunk of stream) {
        if (
          chunk.type === 'content_block_delta' &&
          chunk.delta.type === 'text_delta'
        ) {
          controller.enqueue(new TextEncoder().encode(chunk.delta.text));
        }
      }
      controller.close();
    },
  });

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

Managing Conversation History

Claude's API is stateless — you send the full conversation history with every request. On the client, maintain messages as an array of {role, content} objects. Append user messages immediately for optimistic UI, then append the assistant's complete streamed response when finished. For long conversations approaching the context limit, implement a sliding window or summarisation step to keep costs manageable.

Prompt Caching for Cost Reduction

Prompt caching is one of the highest-ROI optimisations for production AI apps. If your application uses a long system prompt — documentation, a product catalogue, a knowledge base — mark the static portion with cache_control. Anthropic caches these tokens server-side for 5 minutes and reuses them across requests, reducing cost by up to 90% for cached tokens and cutting latency significantly.

const response = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: LARGE_KNOWLEDGE_BASE_TEXT, // thousands of tokens, rarely changes
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [{ role: 'user', content: userMessage }],
});

// Check cache performance in the response
console.log(response.usage.cache_read_input_tokens); // tokens served from cache

Tool Use (Function Calling)

Claude's tool use lets the model call external functions — search APIs, your database, third-party services — and incorporate the results into its final response. Define tools as JSON schemas, implement an agentic loop that executes tool calls and feeds results back, and repeat until Claude returns a final text response.

const tools = [{
  name: 'get_listing_details',
  description: 'Retrieve marketplace listing details by ID',
  input_schema: {
    type: 'object',
    properties: { listing_id: { type: 'string' } },
    required: ['listing_id'],
  },
}];

async function runAgent(userMessage) {
  let messages = [{ role: 'user', content: userMessage }];
  while (true) {
    const response = await client.messages.create({
      model: 'claude-sonnet-4-6',
      max_tokens: 1024,
      tools,
      messages,
    });
    if (response.stop_reason === 'end_turn') {
      return response.content.find((b) => b.type === 'text').text;
    }
    const toolUse = response.content.find((b) => b.type === 'tool_use');
    const result = await executeToolCall(toolUse.name, toolUse.input);
    messages = [
      ...messages,
      { role: 'assistant', content: response.content },
      { role: 'user', content: [{ type: 'tool_result', tool_use_id: toolUse.id, content: JSON.stringify(result) }] },
    ];
  }
}

Building a RAG Pipeline

For AI assistants over private data, combine Claude with a vector database. Embed the user's query using an embedding model (Voyage AI or OpenAI embeddings), retrieve the top-k most relevant chunks from your vector store (Pinecone, Supabase pgvector, or Chroma), and pass those chunks in Claude's system prompt with cache_control enabled. Since only the user's question changes between requests, the large document context is served from cache — making RAG applications dramatically cheaper at scale.

Rate Limiting and Error Handling

In production, implement per-user rate limiting at the Route Handler level. A Redis sliding window — for example, 10 requests per minute per authenticated user — prevents abuse. The Anthropic SDK retries on 529 and 5xx errors with exponential backoff automatically. Log every API call with user ID and token counts from response.usage — understanding usage patterns is essential for forecasting and cost control at scale.

Choosing the Right Model

Match the model to the task. Claude Sonnet 4.6 handles the majority of production use cases — conversational AI, code generation, document analysis — with an excellent cost-to-capability ratio. Claude Opus 4.8 is for tasks where quality matters more than cost: complex multi-step reasoning, nuanced creative work, or agentic workflows that require strong judgment. Claude Haiku 4.5 targets high-volume, latency-sensitive tasks where speed and cost are the priority.