How do you return a streamed response from a route handler in the Next.js App Router, and why can a response built with NextResponse.json() never stream?

## Streaming is a platform feature here, not a Next API Because a route handler returns a Web `Response`, and a `Response` body may be a `ReadableStream`, streaming needs no framework support at all. This is one of the genuine payoffs of the App Router having been built on the platform objects: the code you write is the same code you would write in any fetch-based server, and it is testable by calling the exported handler with a hand-built `Request` and reading the returned stream. ## Building the stream The standard shape is a `ReadableStream` with a `start` callback that receives a controller: ```ts const encoder = new TextEncoder() const stream = new ReadableStream({ async start(controller) { for await (const piece of produceSomething()) { controller.enqueue(encoder.encode(piece)) } controller.close() }, }) ``` Three details matter. Chunks must be binary — a `Uint8Array`, which is what `TextEncoder.encode` produces. Enqueuing a plain string is the single most common mistake and fails rather than silently working. `controller.close()` is mandatory: without it the response never ends and the client hangs until a timeout somewhere kills it. And `start` may be async, which is what lets you await each upstream piece before enqueuing it. ## Returning it ```ts return new Response(stream, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', }, }) ``` The headers are sent immediately, before a single chunk exists. That is the point — the client gets a response and starts reading while you are still producing. ## Why json() cannot do this `Response.json(value)` and `NextResponse.json(value)` accept a complete JavaScript value, serialize it to a string, and use that string as the body. The signature forbids streaming: the function cannot be called until `value` exists, and by then there is nothing left to stream. Calling it repeatedly does not help either — a handler returns exactly one `Response`, so the second call's result is simply discarded. Candidates who reach for "call json() in a loop" have not internalised that the response is a single object whose body happens to be a stream. ## Cancellation `NextRequest` extends the Web `Request`, so `request.signal` is an `AbortSignal` that fires when the client disconnects. A streaming endpoint that ignores it keeps producing into a socket nobody is reading: a closed browser tab leaves an upstream call or a database cursor running, and on a metered platform you pay for the whole thing. Check `request.signal.aborted` between chunks, or attach an `abort` listener that tears down the upstream work. ```ts if (request.signal.aborted) { controller.close() return } ``` The stream's own `cancel(reason)` callback is the other hook — it runs when the consumer stops reading, and it is the right place to release resources. ## Status codes and mid-stream errors The status line and headers are committed the moment the response begins. If your producer throws after three chunks, you cannot retroactively turn a 200 into a 500. Two options remain: emit an error chunk in whatever framing the client understands and then `controller.close()`, or call `controller.error(err)`, which tears the stream down and surfaces to the client as a truncated body. Neither is as good as a clean status, so design the client to recognise both a well-formed terminator and an abrupt end. This is the tax of streaming, and knowing it is what separates someone who has shipped a streaming endpoint from someone who has read about one. ## Where it fits Streaming handlers are always per-request — there is nothing to prerender — so they belong firmly in the dynamic bucket and must never carry a static segment config. They also hold a connection open for the duration, which is a real resource on any host: long-running streams change your concurrency and function-duration picture in a way that a fast JSON endpoint does not. When output arrives in a burst rather than progressively, a plain buffered response is simpler and cheaper; streaming earns its complexity only when the user genuinely benefits from seeing the first bytes early.