--- title: "Stream Handling" description: "Stream handling in Next.js bridges the gap between heterogeneous rendering environments—supporting Node.js Readable/PassThrough streams, standard Web ReadableStream instances, and incoming HTTP bod..." last_updated: "2026-09-23T10:52:03.111005+00:00" canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/server-runtime/stream-handling" ---
Relevant source files The following files were used as context for generating this wiki page: - [packages/next/src/server/app-render/app-render.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx) - [packages/next/src/server/pipe-readable.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts) - [packages/next/src/server/app-render/stream-ops.node.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.node.ts) - [packages/next/src/server/render-result.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/render-result.ts) - [packages/next/src/server/stream-utils/node-web-streams-helper.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/stream-utils/node-web-streams-helper.ts) - [packages/next/src/server/send-response.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/send-response.ts) - [packages/next/src/server/app-render/action-handler.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/action-handler.ts) - [packages/next/src/server/next-server.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/next-server.ts) - [packages/next/src/client/components/segment-cache/cache.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/segment-cache/cache.ts) - [packages/next/src/server/app-render/use-flight-response.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/use-flight-response.tsx) - [packages/next/src/server/app-render/stream-ops.web.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.web.ts) - [packages/next/src/server/app-render/app-render-prerender-utils.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render-prerender-utils.ts) - [packages/next/src/server/body-streams.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/body-streams.ts) - [packages/next/src/server/base-http/node.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/base-http/node.ts) - [packages/next/src/server/app-render/instant-validation/stream-utils.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/instant-validation/stream-utils.ts) - [packages/next/src/server/send-payload.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/send-payload.ts) - [packages/next/src/server/app-render/stream-ops.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.ts) - [packages/next/src/server/dev/debug-channel.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/debug-channel.ts) - [packages/next/src/server/dev/hot-reloader-turbopack.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/hot-reloader-turbopack.ts) - [packages/next/src/server/dev/hot-reloader-webpack.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/hot-reloader-webpack.ts)
## Overview Stream handling in Next.js bridges the gap between heterogeneous rendering environments—supporting Node.js `Readable`/`PassThrough` streams, standard Web `ReadableStream` instances, and incoming HTTP body streams. During server rendering and response generation, streaming architectures allow server components (RSC) and React Fizz SSR pipelines to emit chunks incrementally to clients, reducing time-to-first-byte (TTFB) and enabling partial prerendering (PPR) or streaming HTML hydration. Sources: [packages/next/src/server/app-render/stream-ops.ts:1-9](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.ts#L1-L9) Because Next.js runs across different runtimes (Node.js vs. Edge) and bundlers (Webpack vs. Turbopack), stream handling employs compile-time switches, conditional adapters, and buffered transform streams. These mechanisms guarantee backpressure management, safe stream teeing and replaying during prerendering, and clean pipe propagation to Node.js `ServerResponse` objects. Sources: [packages/next/src/server/app-render/stream-ops.node.ts:1-10](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.node.ts#L1-L10), [packages/next/src/server/pipe-readable.ts:124-147](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L124-L147) --- ## Stream Abstraction and Compile-Time Switching Next.js unifies Node.js streams and Web streams via conditional compilation and shared interfaces. The core stream operations router (`stream-ops.ts`) dynamically resolves to either `stream-ops.node.ts` or `stream-ops.web.ts` depending on whether `process.env.__NEXT_USE_NODE_STREAMS` is active and whether the target is the Edge runtime. Sources: [packages/next/src/server/app-render/stream-ops.ts:27-31](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.ts#L27-L31) Both underlying modules export an identical type surface defined as `AnyStream`: ```typescript export type AnyStream = ReadableStream | Readable ``` Sources: [packages/next/src/server/app-render/app-render-prerender-utils.ts:4](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render-prerender-utils.ts#L4-L4) This structural identity allows stream operators (such as `continueFizzStream`, `chainStreams`, and `streamToBuffer`) to accept either stream type without runtime casting. When running under Node.js with native stream optimizations enabled, Web Streams produced by React are converted to Node.js `Readable` instances using `Readable.fromWeb()`, allowing Next.js to leverage Node's high-performance pipeline primitives and backpressure management. Sources: [packages/next/src/server/stream-utils/node-web-streams-helper.ts:134-157](https://github.com/blade47/next.js/blob/main/packages/next/src/server/stream-utils/node-web-streams-helper.ts#L134-L157) | Module File | Target Runtime / Condition | Primary Implementation | | :--- | :--- | :--- | | `stream-ops.ts` | Compile-time dispatcher | Selects Node or Web implementation based on environment flags | | `stream-ops.node.ts` | Node.js with `__NEXT_USE_NODE_STREAMS = true` | Uses Node.js `PassThrough`, `Transform`, and `Readable.fromWeb()` | | `stream-ops.web.ts` | Edge runtime or Web Streams mode | Uses standard `ReadableStream`, `TransformStream`, and `.tee()` | Sources: [packages/next/src/server/app-render/stream-ops.ts:27-31](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.ts#L27-L31), [packages/next/src/server/app-render/stream-ops.node.ts:1-17](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.node.ts#L1-L17), [packages/next/src/server/app-render/stream-ops.web.ts:1-29](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.web.ts#L1-L29) --- ## Response Piping and Backpressure Mechanics When delivering rendered output to an HTTP client via `RenderResult.pipeToNodeResponse(res)` or `pipeToNodeResponse()`, Next.js bridges `ReadableStream` or Node `Readable` instances directly to Node.js `ServerResponse` streams. Sources: [packages/next/src/server/render-result.ts:405-417](https://github.com/blade47/next.js/blob/main/packages/next/src/server/render-result.ts#L405-L417) For Web `ReadableStream` inputs, `pipe-readable.ts` creates a custom WritableStream adapter (`createWriterFromResponse`) that manages header flushing, OTEL performance metrics, and backpressure: ```typescript export async function pipeToNodeResponse( readable: ReadableStream, res: ServerResponse, waitUntilForEnd?: Promise ) { try { const { errored, destroyed } = res if (errored || destroyed) return const controller = createAbortController(res) const writer = createWriterFromResponse(res, waitUntilForEnd) await readable.pipeTo(writer, { signal: controller.signal }) } catch (err: any) { if (isAbortError(err)) return throw new Error('failed to pipe response', { cause: err }) } } ``` Sources: [packages/next/src/server/pipe-readable.ts:124-147](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L124-L147) > [!IMPORTANT] > Headers are deliberately not flushed until the first chunk is written (`if (!started) { started = true; res.flushHeaders(); }`). This ensures that status codes, cookies, and headers can still be modified during early stream rendering stages before bytes hit the socket. Sources: [packages/next/src/server/pipe-readable.ts:50-80](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L50-L80) Backpressure is governed by the return value of `res.write(chunk)`. If `res.write()` returns `false`, indicating that the underlying kernel buffer is saturated, the writer awaits the response `drain` event before continuing the pipe operation: ```typescript const ok = res.write(chunk) if (!ok) { await drained.promise drained = new DetachedPromise() } ``` Sources: [packages/next/src/server/pipe-readable.ts:83-98](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L83-L98) --- ## Prerendering and Replayable Streams During static generation or Partial Prerendering (PPR), Next.js must frequently split or re-use a single React Server Components (RSC) render stream across multiple consumers (e.g., generating shell markup, inlined data scripts, and static payloads). Because standard `ReadableStream.tee()` or Node streams cannot be consumed multiple times without specialized handling, Next.js implements `ReplayableNodeStream` and `ReactServerResult`. Sources: [packages/next/src/server/app-render/app-render-prerender-utils.ts:14-99](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render-prerender-utils.ts#L14-L99) ```mermaid flowchart TD A["Node.js Readable Source"] --> B["ReplayableNodeStream"] B --> C["Buffered Chunks Array"] B --> D["Subscribers Set"] C --> E["createReplayStream() #1"] C --> F["createReplayStream() #2"] D --> G["Live Chunks (on 'data')"] E --> H["Consumer A (Fizz SSR)"] F --> I["Consumer B (Inlined Data)"] ``` Sources: [packages/next/src/server/app-render/app-render-prerender-utils.ts:99-221](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render-prerender-utils.ts#L99-L221) `ReplayableNodeStream` buffers incoming chunks into memory while simultaneously notifying active subscribers. When `createReplayStream()` is called, it constructs a new Node.js `Readable` that replays all previously buffered chunks via pull-based `_read()` execution before forwarding live chunks as they arrive: ```typescript const stream = new ReadableCtor({ read() { if (!bufferDrained) { bufferDrained = true for (let i = bufferIndex; i < bufferedChunks.length; i++) { this.push(bufferedChunks[i]) } bufferIndex = bufferedChunks.length if (isDone) { this.push(null) } } }, }) ``` Sources: [packages/next/src/server/app-render/app-render-prerender-utils.ts:179-192](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render-prerender-utils.ts#L179-L192) > [!NOTE] > Buffered chunks are delivered via pull-based `_read()` rather than pushed eagerly. This prevents asynchronous task scheduling from capturing an empty `AsyncLocalStorage` context when `createReplayStream()` is invoked outside request scopes. Sources: [packages/next/src/server/app-render/app-render-prerender-utils.ts:140-149](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render-prerender-utils.ts#L140-L149) --- ## Request Body Streams and Cloneable Bodies Incoming HTTP request bodies (`IncomingMessage`) are processed as streams during API route execution, middleware processing, and Server Action payload decoding. Because a Node.js request stream can only be read once, `getCloneableBody()` provides body duplication capabilities with strict memory limits. Sources: [packages/next/src/server/body-streams.ts:43-58](https://github.com/blade47/next.js/blob/main/packages/next/src/server/body-streams.ts#L43-L58) ```typescript export function getCloneableBody( readable: T, sizeLimit?: number ): CloneableBody { let buffered: Readable | null = null // ... return { cloneBodyStream() { const input = buffered ?? readable const p1 = new PassThrough() const p2 = new PassThrough() let bytesRead = 0 const bodySizeLimit = sizeLimit ?? DEFAULT_BODY_CLONE_SIZE_LIMIT let limitExceeded = false input.on('data', (chunk) => { if (limitExceeded) return bytesRead += chunk.length if (bytesRead > bodySizeLimit) { limitExceeded = true p1.push(null) p2.push(null) return } p1.push(chunk) p2.push(chunk) }) // ... buffered = p2 return p1 } } } ``` Sources: [packages/next/src/server/body-streams.ts:47-115](https://github.com/blade47/next.js/blob/main/packages/next/src/server/body-streams.ts#L47-L115) When `cloneBodyStream()` is invoked, it taps into the input stream via dual `PassThrough` streams (`p1` and `p2`), accumulating a buffered copy (`p2`) while streaming data to the caller (`p1`). If the accumulated payload exceeds `DEFAULT_BODY_CLONE_SIZE_LIMIT` (10MB), a warning is logged and both streams are terminated early to prevent unbounded memory consumption. Sources: [packages/next/src/server/body-streams.ts:6-6](https://github.com/blade47/next.js/blob/main/packages/next/src/server/body-streams.ts#L6-L6), [packages/next/src/server/body-streams.ts:79-116](https://github.com/blade47/next.js/blob/main/packages/next/src/server/body-streams.ts#L79-L116) --- ## Inlined Data Streams and Server Action Decoding For RSC responses rendered during App Router navigation, Flight data chunks must be injected into the HTML document as self-executing script tags (`self.__next_f.push(...)`). This is handled by `createNodeInlinedDataStream` and `createInlinedDataReadableStream`. Sources: [packages/next/src/server/app-render/stream-ops.node.ts:908-935](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.node.ts#L908-L935), [packages/next/src/server/app-render/use-flight-response.tsx:165-220](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/use-flight-response.tsx#L165-L220) The stream reads binary or text chunks from the RSC flight stream, serializes them into JSON instructions, and wraps them in HTML script tags with proper escaping (`htmlEscapeJsonString`). Binary chunks that cannot be decoded as valid UTF-8 strings are automatically converted to Base64 data instructions: ```typescript const base64 = Buffer.from( chunk.buffer, chunk.byteOffset, chunk.byteLength ).toString('base64') htmlInlinedData = htmlEscapeJsonString( JSON.stringify([INLINE_FLIGHT_PAYLOAD_BINARY, base64]) ) ``` Sources: [packages/next/src/server/app-render/use-flight-response.tsx:256-267](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/use-flight-response.tsx#L256-L267) Conversely, when decoding Server Actions (`action-handler.ts`), incoming multipart form data or JSON payloads are validated against `bodySizeLimitBytes` (defaulting to 1MB) using a size-limiting transform stream before being passed to `decodeReply` or `busboy`: ```typescript const sizeLimitTransform = new Transform({ transform(chunk, encoding, callback) { size += Buffer.byteLength(chunk, encoding) if (size > bodySizeLimitBytes) { callback(new ApiError(413, `Body exceeded ${bodySizeLimit} limit.`)) return } callback(null, chunk) }, }) ``` Sources: [packages/next/src/server/app-render/action-handler.ts:901-931](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/action-handler.ts#L901-L931) --- ## Development Debug Channels and Buffering In development mode, Next.js streams React debug channel events and HMR payloads to the browser over WebSockets. To prevent excessive network overhead from small, frequent stream pushes, chunks are batched using `createBufferedTransformStream` (Web Streams) or `createNodeBufferedTransformStream` (Node streams) with a 128KB buffer threshold (`MAX_DEBUG_CHANNEL_BATCH_BYTES`). Sources: [packages/next/src/server/dev/debug-channel.ts:10-12](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/debug-channel.ts#L10-L12), [packages/next/src/server/dev/debug-channel.ts:68-93](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/debug-channel.ts#L68-L93) ```typescript export function createBufferedTransformStream( options: BufferedTransformOptions = {} ): TransformStream { const { maxBufferByteLength = Infinity } = options let bufferedChunks: Array = [] let bufferByteLength: number = 0 let pending: DetachedPromise | undefined const flush = (controller: TransformStreamDefaultController) => { if (bufferedChunks.length === 0) return const chunk = new Uint8Array(bufferByteLength) let copiedBytes = 0 for (let i = 0; i < bufferedChunks.length; i++) { chunk.set(bufferedChunks[i], copiedBytes) copiedBytes += bufferedChunks[i].byteLength } bufferedChunks.length = 0 bufferByteLength = 0 controller.enqueue(chunk) } // ... } ``` Sources: [packages/next/src/server/stream-utils/node-web-streams-helper.ts:227-261](https://github.com/blade47/next.js/blob/main/packages/next/src/server/stream-utils/node-web-streams-helper.ts#L227-L261) The transformation buffers incoming chunks until `bufferByteLength >= maxBufferByteLength`, or schedules an immediate flush via microtask (`scheduleImmediate`) if the buffer is below the limit, ensuring low latency while batching small packets. Sources: [packages/next/src/server/stream-utils/node-web-streams-helper.ts:263-292](https://github.com/blade47/next.js/blob/main/packages/next/src/server/stream-utils/node-web-streams-helper.ts#L263-L292) When an HMR event or HTML request debug channel is established, `connectReactDebugChannel` resolves the stream type, applies this buffered transform stream, and pushes data chunks to the browser. Sources: [packages/next/src/server/dev/debug-channel.ts:28-97](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/debug-channel.ts#L28-L97), [packages/next/src/server/dev/hot-reloader-turbopack.ts:1278-1282](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/hot-reloader-turbopack.ts#L1278-L1282) --- ## Call-Chain Execution Walkthrough: Response Pipe Operation The following sequence traces how a rendered output (`RenderResult`) is piped to an HTTP client response object: Sources: [packages/next/src/server/render-result.ts:405-417](https://github.com/blade47/next.js/blob/main/packages/next/src/server/render-result.ts#L405-L417) 1. **`RenderResult.pipeToNodeResponse(res)`** checks if the response payload is a Node.js `Readable` stream. If so, it delegates to `pipeNodeReadableToNodeResponse()`; otherwise, it extracts `.readable` (a Web `ReadableStream`) and calls `pipeToNodeResponse()`. Sources: [packages/next/src/server/render-result.ts:405-417](https://github.com/blade47/next.js/blob/main/packages/next/src/server/render-result.ts#L405-L417) 2. **`pipeToNodeResponse()`** creates an `AbortController` bound to the underlying `ServerResponse` close/error events via `createAbortController(res)`, initializes `createWriterFromResponse()`, and executes `readable.pipeTo(writer, { signal })`. Sources: [packages/next/src/server/pipe-readable.ts:124-147](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L124-L147) 3. **`createWriterFromResponse.write(chunk)`** intercepts the first emitted chunk, flushes response headers (`res.flushHeaders()`), records OTEL client component metrics, and calls `res.write(chunk)`. Sources: [packages/next/src/server/pipe-readable.ts:20-84](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L20-L84) 4. **Backpressure Check:** If `res.write(chunk)` returns `false`, the writer awaits `drained.promise` (which resolves on the Node `drain` event) before proceeding. Sources: [packages/next/src/server/pipe-readable.ts:83-98](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L83-L98) 5. **Completion:** Upon stream completion, `close()` awaits any pending `waitUntil` background promises before calling `res.end()` and resolving the finish promise. Sources: [packages/next/src/server/pipe-readable.ts:109-121](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L109-L121) ```mermaid sequenceDiagram participant RR as RenderResult participant PNR as pipeToNodeResponse participant WR as createWriterFromResponse participant SR as ServerResponse RR->>PNR: pipeToNodeResponse(readable, res, waitUntil) PNR->>WR: createWriterFromResponse(res, waitUntil) PNR->>SR: readable.pipeTo(writer, { signal }) loop For each chunk SR->>WR: write(chunk) alt First chunk WR->>SR: flushHeaders() end WR->>SR: res.write(chunk) alt Backpressure (false) SR-->>WR: drain event end end SR-->>WR: close / finish event WR->>SR: await waitUntil, res.end() ``` Sources: [packages/next/src/server/render-result.ts:405-417](https://github.com/blade47/next.js/blob/main/packages/next/src/server/render-result.ts#L405-L417), [packages/next/src/server/pipe-readable.ts:20-147](https://github.com/blade47/next.js/blob/main/packages/next/src/server/pipe-readable.ts#L20-L147) --- ## Stream Operations Design Trade-Offs | Design Choice | Benefit | Cost / Trade-off | | :--- | :--- | :--- | | **Compile-Time Stream Switcher** (`stream-ops.ts`) | Eliminates runtime overhead and dead-code branches in edge vs. node bundles | Requires maintaining dual module implementations (`stream-ops.node.ts` & `stream-ops.web.ts`) with identical type surfaces | | **Pull-Based Replay Buffering** (`ReplayableNodeStream`) | Prevents eager chunk emission from capturing empty `AsyncLocalStorage` contexts | Requires buffering stream chunks in memory until consumers read them | | **Dual PassThrough Body Cloning** (`getCloneableBody`) | Allows simultaneous consumption by Middleware and route handlers | Doubles memory allocation for request bodies up to the size limit | | **Buffered Debug Transformation** (`createBufferedTransformStream`) | Reduces WebSocket message frequency and serialization overhead by batching up to 128KB | Introduces minor buffering latency for debug chunk delivery | Sources: [packages/next/src/server/app-render/stream-ops.ts:27-31](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/stream-ops.ts#L27-L31), [packages/next/src/server/app-render/app-render-prerender-utils.ts:99-149](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render-prerender-utils.ts#L99-L149), [packages/next/src/server/body-streams.ts:79-116](https://github.com/blade47/next.js/blob/main/packages/next/src/server/body-streams.ts#L79-L116), [packages/next/src/server/dev/debug-channel.ts:10-12](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/debug-channel.ts#L10-L12) ## Related - [App Server Rendering](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/app-router-rendering/app-server-rendering) - [Staged Dynamic Rendering](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/app-router-rendering/staged-dynamic-rendering) ## Sitemap See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.