feat(node-streams): add primitives, build infra, and config flag (6/8)#89859
Draft
feedthejim wants to merge 2 commits intocanaryfrom
Draft
feat(node-streams): add primitives, build infra, and config flag (6/8)#89859feedthejim wants to merge 2 commits intocanaryfrom
feedthejim wants to merge 2 commits intocanaryfrom
Conversation
2 tasks
Contributor
Author
This was referenced Feb 11, 2026
feedthejim
changed the title
feedthejim
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
bf6e861 to
5d447ac
Compare
feedthejim
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
75234d5 to
22d9b4f
Compare
nextjs-bot
added
created-by: Next.js team
feedthejim
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
5d447ac to
99fdd5a
Compare
feedthejim
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
22d9b4f to
6b4ea2a
Compare
This was referenced Feb 11, 2026
feedthejim
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
99fdd5a to
99bd282
Compare
feedthejim
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
6b4ea2a to
54df7a3
Compare
2 tasks
feedthejim
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
54df7a3 to
c5ede11
Compare
feedthejim
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
99bd282 to
8813630
Compare
feedthejim
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
c5ede11 to
ac9e39f
Compare
feedthejim
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
8813630 to
4199831
Compare
Collaborator
Stats from current PR🔴 3 regressions
📊 All Metrics📖 Metrics GlossaryDev Server Metrics:
Build Metrics:
Change Thresholds:
⚡ Dev Server
📦 Dev Server (Webpack) (Legacy)📦 Dev Server (Webpack)
⚡ Production Builds
📦 Production Builds (Webpack) (Legacy)📦 Production Builds (Webpack)
📦 Bundle SizesBundle Sizes⚡ TurbopackClient Main Bundles: **399 kB** → **399 kB** ✅ -23 B80 files with content-based hashes (individual files not comparable between builds) Server Middleware
Build DetailsBuild Manifests
📦 WebpackClient Main Bundles
Polyfills
Pages
Server Edge SSR
Middleware
Build DetailsBuild Manifests
Build Cache
🔄 Shared (bundler-independent)Runtimes
📝 Changed Files (37 files)Files with changes:
View diffsapp-page-exp..ntime.dev.jsfailed to diffapp-page-exp..time.prod.jsDiff too large to display app-page-exp..ntime.dev.jsfailed to diffapp-page-exp..time.prod.jsfailed to diffapp-page-nod..ntime.dev.jsfailed to diffapp-page-nod..time.prod.jsDiff too large to display app-page-tur..ntime.dev.jsfailed to diffapp-page-tur..time.prod.jsDiff too large to display app-page-tur..ntime.dev.jsfailed to diffapp-page-tur..time.prod.jsfailed to diffapp-page-tur..ntime.dev.jsfailed to diffapp-page-tur..time.prod.jsDiff too large to display app-page-tur..ntime.dev.jsfailed to diffapp-page-tur..time.prod.jsfailed to diffapp-page.runtime.dev.jsfailed to diffapp-page.runtime.prod.jsfailed to diffapp-route-ex..ntime.dev.jsDiff too large to display app-route-ex..time.prod.jsDiff too large to display app-route-no..ntime.dev.jsDiff too large to display app-route-no..time.prod.jsDiff too large to display app-route-tu..ntime.dev.jsDiff too large to display app-route-tu..time.prod.jsDiff too large to display app-route-tu..ntime.dev.jsDiff too large to display app-route-tu..time.prod.jsDiff too large to display dist_client_..ntime.dev.js@@ -0,0 +1,2 @@
+"use strict";exports.ids=["dist_client_dev_noop-turbopack-hmr_js"],exports.modules={"./dist/client/dev/noop-turbopack-hmr.js"(module,exports1){function connect(){}Object.defineProperty(exports1,"__esModule",{value:!0}),Object.defineProperty(exports1,"connect",{enumerable:!0,get:function(){return connect}}),("function"==typeof exports1.default||"object"==typeof exports1.default&&null!==exports1.default)&&void 0===exports1.default.__esModule&&(Object.defineProperty(exports1.default,"__esModule",{value:!0}),Object.assign(exports1.default,exports1),module.exports=exports1.default)}};
+//# sourceMappingURL=dist_client_dev_noop-turbopack-hmr_js-experimental-nodestreams.runtime.dev.js.map
\ No newline at end of filedist_client_..ntime.dev.js@@ -0,0 +1,2 @@
+"use strict";exports.ids=["dist_client_dev_noop-turbopack-hmr_js"],exports.modules={"./dist/client/dev/noop-turbopack-hmr.js"(module,exports1){function connect(){}Object.defineProperty(exports1,"__esModule",{value:!0}),Object.defineProperty(exports1,"connect",{enumerable:!0,get:function(){return connect}}),("function"==typeof exports1.default||"object"==typeof exports1.default&&null!==exports1.default)&&void 0===exports1.default.__esModule&&(Object.defineProperty(exports1.default,"__esModule",{value:!0}),Object.assign(exports1.default,exports1),module.exports=exports1.default)}};
+//# sourceMappingURL=dist_client_dev_noop-turbopack-hmr_js-nodestreams.runtime.dev.js.map
\ No newline at end of filedist_client_..ntime.dev.js@@ -0,0 +1,2 @@
+"use strict";exports.ids=["dist_client_dev_noop-turbopack-hmr_js"],exports.modules={"./dist/client/dev/noop-turbopack-hmr.js"(module,exports1){function connect(){}Object.defineProperty(exports1,"__esModule",{value:!0}),Object.defineProperty(exports1,"connect",{enumerable:!0,get:function(){return connect}}),("function"==typeof exports1.default||"object"==typeof exports1.default&&null!==exports1.default)&&void 0===exports1.default.__esModule&&(Object.defineProperty(exports1.default,"__esModule",{value:!0}),Object.assign(exports1.default,exports1),module.exports=exports1.default)}};
+//# sourceMappingURL=dist_client_dev_noop-turbopack-hmr_js-turbo-experimental-nodestreams.runtime.dev.js.map
\ No newline at end of filedist_client_..ntime.dev.js@@ -0,0 +1,2 @@
+"use strict";exports.ids=["dist_client_dev_noop-turbopack-hmr_js"],exports.modules={"./dist/client/dev/noop-turbopack-hmr.js"(module,exports1){function connect(){}Object.defineProperty(exports1,"__esModule",{value:!0}),Object.defineProperty(exports1,"connect",{enumerable:!0,get:function(){return connect}}),("function"==typeof exports1.default||"object"==typeof exports1.default&&null!==exports1.default)&&void 0===exports1.default.__esModule&&(Object.defineProperty(exports1.default,"__esModule",{value:!0}),Object.assign(exports1.default,exports1),module.exports=exports1.default)}};
+//# sourceMappingURL=dist_client_dev_noop-turbopack-hmr_js-turbo-nodestreams.runtime.dev.js.map
\ No newline at end of filepages-api-tu..ntime.dev.jsDiff too large to display pages-api-tu..time.prod.jsDiff too large to display pages-api.runtime.dev.jsDiff too large to display pages-api.ru..time.prod.jsDiff too large to display pages-turbo...ntime.dev.jsDiff too large to display pages-turbo...time.prod.jsDiff too large to display pages.runtime.dev.jsDiff too large to display pages.runtime.prod.jsDiff too large to display server.runtime.prod.jsDiff too large to display 📎 Tarball URL |
feedthejim
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
4199831 to
932773c
Compare
feedthejim
changed the title
feedthejim
changed the title
timneutkens
reviewed
Feb 12, 2026
| ): RenderToPipeableStreamOptions['onHeaders'] | undefined { | ||
| if (!onHeaders) return undefined | ||
| return (headersDescriptor: Headers | HeadersInit) => { | ||
| onHeaders(new Headers(headersDescriptor)) |
Member
There was a problem hiding this comment.
Do we always have to clone this object? Maybe only needed when it's HeadersInit and not when Headers?
timneutkens
reviewed
Feb 12, 2026
| const debugChannel = options.debugChannel | ||
| const isNodeWritable = | ||
| typeof debugChannel === 'object' && | ||
| debugChannel !== null && |
Member
There was a problem hiding this comment.
Because of if(options?.debugChannel)that is wrapped above this check is never true.
timneutkens
reviewed
Feb 12, 2026
| abort?: (reason?: unknown) => void | ||
| } | ||
|
|
||
| export async function renderToFizzStream( |
Member
There was a problem hiding this comment.
Can likely be optimized for JIT
Something like this:
export async function renderToFizzStream(
element: React.ReactElement,
streamOptions: StreamOptions, // specific type
runInContext?: (fn: () => any) => any
): Promise<FizzStreamResult> {
if (runInContext) {
return runInContext(() =>
renderToFizzPipeableStream(
ReactDOMServer.renderToPipeableStream,
element,
streamOptions
)
)
}
return renderToFizzPipeableStream(
ReactDOMServer.renderToPipeableStream,
element,
streamOptions
)
}
timneutkens
reviewed
Feb 12, 2026
| return renderToFizzPipeableStream(renderFn, element, streamOptions) | ||
| } | ||
|
|
||
| export async function resumeToFizzStream( |
Member
There was a problem hiding this comment.
Similar to above comment, can likely be optimized for JIT:
export async function resumeToFizzStream(
element: React.ReactElement,
postponedState: PostponedState,
streamOptions: StreamOptions,
runInContext?: (fn: () => any) => any
): Promise<FizzStreamResult> {
if (runInContext) {
return runInContext(() =>
resumeToFizzPipeableStream(
ReactDOMServer.resumeToPipeableStream,
element,
postponedState,
streamOptions
)
)
}
return resumeToFizzPipeableStream(
ReactDOMServer.resumeToPipeableStream,
element,
postponedState,
streamOptions
)
}
feedthejim
commented
Feb 16, 2026
| } else { | ||
| // Node's fromWeb() overload expects stream/web.ReadableStream. | ||
| // Convert from the global ReadableStream type to satisfy that overload. | ||
| nodeDebugStream = Readable.fromWeb( |
Contributor
Author
There was a problem hiding this comment.
might be dead code
feedthejim
commented
Feb 16, 2026
| * Tees a Node Readable into two Readables without coupling backpressure | ||
| * across branches. | ||
| */ | ||
| export function teeNodeReadable( |
Contributor
Author
There was a problem hiding this comment.
should this be solved differently via readable streams attaching listeners?
this probably comes because claude san tried to keep the same apis
feedthejim
commented
Feb 16, 2026
| postponedState: PostponedState, | ||
| options?: ResumeToPipeableOptions | ||
| ): Promise<FizzPipeableStreamResult> { | ||
| return getTracer().trace(AppRenderSpan.renderToReadableStream, async () => { |
Contributor
Author
There was a problem hiding this comment.
are spans conserved on the node version?
Member
There was a problem hiding this comment.
i don't remember how our spans are implemented, but if it uses ALS, probably not!
https://github.com/vercel/next.js/pull/89859/changes#discussion_r2863051317
feedthejim
commented
Feb 16, 2026
|
|
||
| const originalOnAllReady = options?.onAllReady | ||
| // Same onHeaders wrapping as renderToFizzPipeableStream | ||
| const wrappedOnHeaders = wrapOnHeaders(options?.onHeaders) |
Contributor
Author
There was a problem hiding this comment.
was this needed? need to reinvestigate
feedthejim
commented
Feb 16, 2026
| ): Promise<FizzStreamResult> { | ||
| const run: <T>(fn: () => T) => T = runInContext ?? ((fn) => fn()) | ||
| const renderFn = (...args: any[]) => | ||
| run(() => (ReactDOMServer as any).renderToPipeableStream(...args)) |
feedthejim
commented
Feb 16, 2026
| Promise<unknown> | ||
| >() | ||
| const encoder = new TextEncoder() | ||
| const INLINE_FLIGHT_PAYLOAD_SUFFIX = ')</script>' |
Contributor
Author
There was a problem hiding this comment.
could be done in a separate PR
feedthejim
commented
Feb 16, 2026
| * Each stream is fully consumed before moving to the next. | ||
| */ | ||
| export function chainNodeStreams(...streams: Readable[]): Readable { | ||
| const { PassThrough: PT } = getNodeStream() |
timneutkens
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
229dd11 to
cdc35bb
Compare
timneutkens
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
4ccf817 to
6a196c8
Compare
timneutkens
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
cdc35bb to
694434e
Compare
timneutkens
force-pushed
the
feedthejim/node-stream-03-primitives
branch
2 times, most recently
from
36ff037 to
35c5f12
Compare
timneutkens
force-pushed
the
feedthejim/node-stream-02-extract
branch
2 times, most recently
from
1cb6828 to
f324ca1
Compare
timneutkens
force-pushed
the
feedthejim/node-stream-03-primitives
branch
3 times, most recently
from
05531f7 to
79b103c
Compare
timneutkens
force-pushed
the
feedthejim/node-stream-02-extract
branch
from
258bc9f to
488d4c7
Compare
…ig flag Add the building blocks for native Node.js stream rendering: - Config flag: experimental.useNodeStreams with __NEXT_USE_NODE_STREAMS env var - Node stream primitives: node-stream-helpers, pipeable-stream-wrappers, node-stream-tee, pipe-readable, chain-node-streams - Stream ops: stream-ops.node.ts with compile-time switcher in stream-ops.ts - Debug channel: debug-channel-server.node.ts with 3-way conditional switcher - Build: taskfile.js bundle tasks, webpack config routing, module.compiled.js - Flight response: createInlinedDataNodeStream for Node Transform encoding - Entry base: conditional exports for renderToPipeableStream/prerenderToNodeStream - Tests: pipe-readable, flight response node stream, env precedence e2e
This was referenced Feb 24, 2026
timneutkens
force-pushed
the
feedthejim/node-stream-03-primitives
branch
from
79b103c to
558f424
Compare
Collaborator
Failing test suitesCommit: 558f424 | About building and testing Next.js
Expand output● react-dom/server in React Server environment › explicit react-dom/server.edge usage in app code ● react-dom/server in React Server environment › explicit react-dom/server.edge usage in library code
Expand output● next-server-nft › with output:standalone › should not trace too many files in next-server.js.nft.json |
lubieowoce
requested changes
Feb 27, 2026
| }) | ||
| } | ||
| const onSourceEnd = () => { | ||
| runInContext(() => { |
Member
There was a problem hiding this comment.
as currently used, this whole runInContext pattern is wrong. it preserves workUnitAsyncStorage (because that's what we provide in the callbacks that are passed in here) but no other ALSes, so e.g. workAsyncStorage would still get lost. We should do this instead, that's what AsyncLocalStorage.bind is for (bindSnapshot is a wrapper for it):
const onSourceData = bindSnapshot((chunk) => ...)
you could also use const runInContext = AsyncLocalStorage.snapshot() to get a correct version of runInContext, but i think that makes the code messier than it needs to be. The caller of the stream op shouldn't need to care about this, AsyncLocalStorage.bind inside is cleaner.
See #90609 for a PR to remove runInContext from current canary. we should do that and rework the bits in here to match.
lubieowoce
reviewed
Feb 27, 2026
Member
There was a problem hiding this comment.
where's this sourced from? summarizing stuff is nice and all but it'd be good to have some references in here in case we want to check if this is still current sometime in the future
lubieowoce
added a commit
that referenced
this pull request
Feb 27, 2026
The `runInContext` pattern that's used all over `stream-ops` is weird and feels very unnecessary -- we're passing in callbacks that just get invoked immediately, and all they do is call `AsyncLocalStorage.run`. We should just use the standard `AsyncLocalStorage.run` method outside instead. I commented about getting rid of it somewhere on the original node streams PR, but that got lost when it was was split up. I believe the original reasoning for addding it at all was that some of the node-streams implementations needed to preserve async context for callbacks -- see eg [here](https://github.com/vercel/next.js/blob/558f4248e5e5641d78b865a291c099791460d486/packages/next/src/server/app-render/node-stream-tee.ts#L244). But if that's the motivation, then the current `runInContext` pattern **is wrong anyway** -- sure, it preserves `workUnitAsyncStorage`, but doesn't preserve `workAsyncStorage` and whetever other ALSes may be present, so it's not semantically correct. If this is the goal, then the relevant callbacks should use `bindSnapshot` (i.e. `AsyncLocalStorage.bind`) instead, because it preserves the entire context, not just one ALS. (Note that technically the `runInContext` pattern is salvageable if we just always pass `AsyncLocalStorage.snapshot()`, but then i see no reason why the caller should have to do that. `AsyncLocalStorage.bind` is cleaner) Note that this'll require changes in #89859
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add all building blocks for native Node.js stream rendering, gated behind
experimental.useNodeStreams(off by default).Config flag wiring:
useNodeStreamsinExperimentalConfig, schema,__NEXT_USE_NODE_STREAMSenv varnext-server.tsandexport/worker.tsNode stream primitives (new files):
node-stream-helpers.ts(~1,022 lines): core operations (continue*, chain, buffer, prelude, tag scanning)pipeable-stream-wrappers.ts: React renderToPipeableStream/resumeToPipeableStream bridgesnode-stream-tee.ts: O(1) dequeue tee for node streamspipe-readable.ts: backpressure-aware pipe to ServerResponsechain-node-streams.ts: sequential stream chainingCompile-time switcher upgrade:
stream-ops.ts: conditionalrequire('./stream-ops.node')vsrequire('./stream-ops.web')stream-ops.node.ts: node implementation of all stream opsdebug-channel-server.ts: 3-way conditional (edge/node-streams/default)debug-channel-server.node.ts: native Node.js debug channel with Readable/Writable pairBuild infrastructure:
taskfile.js: 8 new bundle tasks for node stream variantsnext-runtime.webpack-config.js: nodeStreams optionmodule.compiled.js: runtime bundle routingModified files:
entry-base.ts: conditional exports forrenderToPipeableStream/prerenderToNodeStreamuse-flight-response.tsx:createInlinedDataNodeStreamTransform,getFlightStreamnode pathTest plan
pnpm --filter=next typespassespnpm test-unit packages/next/src/server/pipe-readable.test.tspassesNEXT_SKIP_ISOLATE=1 pnpm testonly test/unit/app-render/use-flight-response-node-stream.test.tspassespnpm test-dev-turbo test/e2e/app-dir/use-node-streams-env-precedence/passes