Anthropic streaming on Next.js App Router: return a streaming Response from the route handler, key stays server-side

TL;DR

Set the response Content-Type to text/event-stream when the client reads it as an event stream. Route handlers run on the server, which is where the API key must live.

Steps

1. Put the code in a route handler (app/api/chat/route.ts). Route handlers run on the server, which is where the API key must live. Never use a public-prefixed variable for the key and never call the SDK from a client component.
2. Inside POST, start the message stream with the TypeScript SDK, then return a new Response wrapping a ReadableStream that you feed from the event iterator. The SDK's .finalMessage() helper can accumulate the complete message if you need it server-side, but for streaming to the browser you forward events as they arrive.
3. Forward only text_delta event payloads into the stream. Skip message_start, content_block_start, content_block_stop, message_delta; they carry no user-visible text. Handle unknown event types with a skip branch, per Anthropic's versioning policy.
4. Accumulate input_json_delta per content-block index if the route also supports tool use; only JSON-parse at content_block_stop. Parsing a partial fragment throws.
5. Close the stream controller on message_stop and on errors. An unclosed controller leaves the fetch hanging on the client.
6. Set the response Content-Type to text/event-stream when the client reads it as an event stream.
7. Failure modes this prevents: leaking the key through a public env var or a client component; trying to use Express-style response writes in a route handler; crashing the route on a newly added event type.

When to use

You are seeing this: Put the code in a route handler (app/api/chat/route.ts). Use this skill when you run into "Anthropic streaming on Next.js App Router: return a streaming Response from the route handler, key stays server-side".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The streaming reference documents the event flow, per-block indices, the inputjsondelta accumulation rule, and the graceful-unknown-event-type rule. Verified live at https://docs.anthropic.com/en/api/streaming and https://docs.anthropic.com/en/docs/build-with-claude/streaming.