- 25 Jul, 2026 19 commits
-
-
next-js-bot[bot] authored
-
Pete Hunt authored
### What? Fire-and-forget `setTimeout` calls in the Edge runtime sandbox (e.g. from middleware) are tracked forever by Next.js's sandbox `TimeoutsManager`, even after the timeout has run. In a long-lived standalone/self-hosted server this makes tracked timeout resources grow monotonically, producing step-like heap growth and eventual OOM. ### Why? `TimeoutsManager.add()` pushes each timeout id into a `resources` array. When a one-shot timeout fires naturally, `webSetTimeoutPolyfill`'s `finally` clears the underlying Node timer (the workaround for nodejs/node#53335) but never removes the id from the manager. The id is dropped only if user code calls `clearTimeout(id)` or the whole module context is torn down (`clearModuleContext`, introduced in #57235). The natural-completion path — module context stays alive, timeout finishes on its own — was missing, so ids accumulate for the lifetime of the process. ### How? - `TimeoutsManager.create()` now wraps the callback so the timeout untracks its own id once it has run. The Node-timer workaround and the `this`/args binding in `webSetTimeoutPolyfill` are preserved. - Refactored the base `ResourceManager.remove()` into `untrack()` (stop tracking) + `destroy()`, so natural completion can release tracking without a redundant `clearTimeout`. - Intervals are intentionally unchanged: they fire repeatedly and must remain tracked until `clearInterval`/`removeAll`. - Added a unit test covering natural release, no monotonic growth across repeated rounds, the `clearTimeout`/`remove` path, callback `this`/args binding, and that intervals stay tracked. Verified: `pnpm --filter=next types` clean, prettier/eslint clean, and the new unit test fails on the current behavior (reverting only the release logic) and passes with the fix. Fixes #95094 --- **Update:** this branch now lands @berry95's commit from #94794 first (`Set`-based resource tracking, which also makes `untrack`/`remove` O(1)), with the fix rebased on top. --------- Co-authored-by:
Berry Kim <wlsdud40@gmail.com> Co-authored-by:
Dan Abramov <dan.abramov@gmail.com>
-
dan authored
In a project whose absolute path contains characters that percent-encode in URLs — e.g. a space — the dev overlay showed no code frame and raw `file://` URLs instead of source locations for server frames. Two encoding mismatches caused this: - Turbopack's `trace_source` percent-decoded the source map's original file URL before comparing it against the still-encoded project root URI, so the containment check failed ("Original file ... outside project") for any project path with such characters. The comparisons now stay in the encoded domain and only the outputs are decoded back into paths. - React synthesizes stack frame `file:` URLs by prepending the scheme to a filesystem path, so the overlay receives URLs with e.g. raw spaces. These aren't well-formed, and they don't match the `url.pathToFileURL` form Node.js keys its source map cache by. The overlay middleware now re-encodes them through WHATWG URL parsing, which tolerates such input. ## Test Plan New tests. Known cases that remain broken are commented out with a TODO. These could be resolved if https://github.com/react/react/pull/37105 or equivalent lands. ## Before <img width="825" height="732" alt="Screenshot 2026-07-25 at 14 39 18" src="https://github.com/user-attachments/assets/0f119e52-ec86-495a-bf5c-5339faa1d606" /> ## After <img width="1126" height="733" alt="Screenshot 2026-07-25 at 14 58 14" src="https://github.com/user-attachments/assets/a263ee8a-4cfe-4358-9a8e-2e58b4b16aa5" /> Co-authored-by:
Claude Fable 5 <noreply@anthropic.com>
-
dan authored
Vibed. This should help with running React PRs on sandboxes to measure impact on `bench/`. ## Usage ``` use bench skill to to measure impact of https://github.com/react/react/pull/37066 ``` - Should be able to point at React or Next PRs - Compares against mergebase - Grabs React builds from CI when possible - Before benching, asserts both React builds are green, or that tests pass - Runs on many sandboxes with interleaved runs - Caches reusable stuff (builds) between sandboxes - Uses `bench/` examples with realistic payloads ## Test Plan Running a bench: <img width="1445" height="584" alt="Screenshot 2026-07-20 at 03 08 02" src="https://github.com/user-attachments/assets/ac8b6aac-1e62-4695-9a59-fd0577a8a441" /> Bench that shows good results: <img width="1078" height="725" alt="Screenshot 2026-07-20 at 03 46 20" src="https://github.com/user-attachments/assets/ce49a806-f1b1-497c-a3dd-e5f8d08ea25b" /> Neutral bench: <img width="1032" height="455" alt="Screenshot 2026-07-20 at 03 47 27" src="https://github.com/user-attachments/assets/de3b700c-4875-4c70-b1c1-55cdddd73a1a" /> --------- Co-authored-by:
Claude Fable 5 <noreply@anthropic.com>
-
Hendrik Liebau authored
Node.js caches source maps per isolate, so the dev validation worker only has maps for the chunk files loaded on its own thread. For chunks it never loads, such as a module behind a dynamic `import()`, it reads the `.map` that Turbopack writes next to the chunk. Webpack keeps its dev source maps in the compiler instead, so the worker has nothing to read and reports those frames with the position they have in the compiled output rather than in the source. This stops using the worker when the bundler is Webpack, so validation runs in process again, where those frames resolve, and `experimental.devValidationWorker` now has no effect there. Dev performance under Webpack goes back to what it was before validation moved to a worker, which is the better trade: the worker exists to keep the event loop responsive during rapid navigation, and that is not worth losing the source location on validation errors.
-
Hendrik Liebau authored
Node.js caches source maps per isolate, so the dev validation worker only has maps for the chunk files loaded on its own thread. It never renders server components, and the built entry reaches segment modules through lazy getters, so it loads whatever `loadComponents` pulls in and nothing else. A module the bundler splits into a chunk of its own, as Turbopack does for a dynamic `import()`, is therefore missing from that cache entirely, and the frames pointing into it are logged without a source location. In-process validation resolves them, so this is a regression from moving validation onto a worker. On the main thread the same miss is covered by asking Turbopack for the map through the `Project` handle, which cannot cross a thread boundary. The worker instead reads the `.map` that Turbopack already wrote next to the chunk, which needs no project handle and, unlike Node's cache, does not depend on the chunk having been evaluated on this thread. Lookups are restricted to `distDir` so a stack frame cannot point the reader at an arbitrary file, and both hits and misses are memoised. Installing that lookup also required moving `bundlerFindSourceMapPayload` onto a `globalThis` symbol. `patch-error-inspect` is bundled into several runtimes that each get their own copy, and the copy that registers the implementation, here the worker bundle, is not the copy that symbolicates the frame, which is the app-page bundle's. The code frame renderer in the same file is already shared this way for the same reason. Webpack keeps its dev source maps in the compiler rather than writing them next to the chunks, so there is nothing for the worker to read and its frames are unchanged. A follow-up turns the worker off for Webpack so that validation runs in process, where those frames still resolve.
-
Hendrik Liebau authored
Running `test/e2e/app-dir/instant-validation/suspense-boundaries.test.ts` locally on Node.js 24 currently fails in the two "missing suspense around search params" cases: stacks that should read `app/…/page.tsx:40:18` are logged as raw `about://React/Prefetch/file:///…/%5Broot-of-the-server%5D…` URLs, so the validation errors printed to the terminal no longer point at any source. CI is green on the same commit, because it runs Node.js 20. The dev validation worker (#96153) and the switch to `file:` source maps for Turbopack (#95946) landed hours apart, and the worker's branch predated the source map change, so the two first met on canary, where the older Node.js hid the result. Symbolicating a frame that React spliced in from another environment means decoding the chunk path out of its `about://React/…` URL and asking Node.js for that chunk's source map. Decoding returns the path as written, while Node.js keys its cache by the `pathToFileURL` encoding of the same path, and from Node.js 22 on that encoding escapes the brackets in Turbopack's `[root-of-the-server]` chunk names, so the lookup misses. Node.js 20 leaves brackets alone, which is why the same code resolves there. PR #95946 anticipated the mismatch and left it as a follow-up, because on the main thread a miss is only wasteful: Turbopack hands back the chunk's map instead, which means parsing one the process had already parsed and cached. The validation worker runs on its own thread with no access to the Turbopack project, so there the miss is final. Node.js also accepts the plain path as a cache key, unambiguously for both a CommonJS absolute path and an ESM `file:` URL, so we retry with it before giving up. Making React's fake frame URLs reversible, as proposed in https://github.com/react/react/pull/37105, would let the first lookup succeed on its own and retire the retry. The test added here pins down what the worker can symbolicate at all. It caches maps per chunk file in its own isolate and never renders server components, so a statically imported module sits in a chunk it has already loaded and resolves, while a dynamically imported one gets a chunk of its own that is never loaded and does not. The snapshots for that second route record broken output on purpose: in-process validation resolves the frame, so losing it is a regression from moving validation onto a worker, and it affects Turbopack (no location) and Webpack (compiled positions) alike. Follow-ups address each. The snapshots are recorded with the retry applied rather than before it. Without it Turbopack's output differs between Node.js 20 and 22, and the broken URLs embed the test's temporary install directory, which changes on every run, so no stable recording exists. One consequence is that CI cannot fail on a regression of the retry itself; that was checked by running the new suite under Node.js 24.
-
Hendrik Liebau authored
The dev validation snapshot flattened both fallback param sets into arrays of entries before handing them to the worker, and the worker rebuilt a `Map` from each one on the other side. Neither step is needed, because the structured clone that carries the snapshot across the `worker_threads` boundary supports `Map` natively, so the maps can travel as they are. Dropping the conversion on both ends also lets the two snapshot fields be typed as `OpaqueFallbackRouteParams` directly, and it makes them consistent with `rootParams` and `implicitTags`, which the snapshot already passes through untouched. The neighbouring `headers` spread stays as it is, because `Headers` is not a structured-cloneable type and those entries genuinely do have to be materialized before the snapshot is sent.
-
dan authored
Follow-up to https://github.com/vercel/next.js/pull/95946. Every fake stack frame is eval'd as its own script, so error formatting resolved a source map once per frame. This sucks for two reasons: `SourceMap#payload` returns a deep clone of the payload *on every access*, and constructing a `SyncSourceMapConsumer` indexes the whole payload. So an error with 50 fake frames pointing into one chunk cloned that chunk's map 50 times and indexed it 50 times. This change caches both steps per map instead of per script. `findSourceMapPayload` wraps `module.findSourceMap` and reads payload only once per `SourceMap` instance. This works because Node.js keeps one instance per script, so the instance is a reliable identity for "same map". (This also helps `filterStackFrameDEV`, which cloned the payload for every frame it filtered.) Consumers are cached in a WeakMap with (payload, base URL) pairs as a key since that's what they vary by. (Note that consumer sharing only works because the payload memo makes references stable, that's why they're in one commit.) This lets us share computation for identical sourcemaps despite them being used by different virtual frames. I previously tried to do this by keying a map from a physical filename to the sourcemap, but as noted in https://github.com/vercel/next.js/pull/95946#discussion_r3613450061, each fake frame could technically receive a different map, even if we don't do that. Caching based on returned value's identity lets us preserve the ability to be more granular later without worrying that the cache will start behaving incorrectly. ## Test Plan Microbench (20 errors × 20 fake frames, 5.6MB map, native path): canary 688.2 ms/error → this commit 0.2 ms/error. On a real devserver route with an artificially deep error (50-deep stacks in a chunk with a 19MB map), the route serve time goes down from ~400ms to ~70ms. Co-authored-by:
Claude Fable 5 <noreply@anthropic.com>
-
Pete Hunt authored
## Summary Fixes #94919. When a client disconnects mid-response, the compression middleware's zlib stream is never released, and every aborted compressed response permanently retains its deflate state (~256 KiB). On a server taking traffic that aborts mid-stream (bots, CDNs, users navigating away) RSS climbs until the process is OOM-killed. `router-server.ts` applies the vendored `compression` middleware, which ends its zlib stream *only* from inside its own `res.end()` wrapper. On a client disconnect Next destroys the response instead, so that wrapper never runs and the stream stays open. An open zlib stream is pinned by its native handle, so it is not merely uncollected-for-now — it survives GC entirely. This is why the reported symptom looks unlike a normal JS leak: the JS heap stays nearly flat while RSS grows without bound, because the retained deflate state is native memory. It affects `next start`, `next dev`, and custom servers — anything going through the router server with the default `compress: true`. Deployments that let a proxy handle compression never see it. Note that ending the stream is not sufficient to recover it: its `data` handler writes to the already-destroyed response, `res.write()` returns `false`, the middleware pauses the stream, and it never reaches `end`. It has to be destroyed. `releaseCompressionStream` carries a comment explaining this so the cleanup isn't "simplified" back into a no-op later. The stream is reached through the one handle the middleware exposes: it forwards `res.on('drain', …)` to the zlib stream once that stream exists, and `EventEmitter#on` returns the emitter it was called on. Upstream `compression@1.8.1` still has no premature-close handling, so this can't be fixed by bumping the vendored copy. The added test asserts that assumption and will fail if a future vendored version handles this itself, signalling that the workaround can be dropped. ### Before / after Measured with a minimal custom Node server (no Express/axios) rendering a 1.25 MB dynamic App Router page, 8 rounds × 300 requests cancelled after the first chunk, `heapUsed`/`rss` sampled **after forced GC** each round. Same build, cleanup toggled behind a temporary env var: | | without cleanup | with cleanup | | --- | --- | --- | | zlib contexts never released | 2400 of 2400 (100%) | **0** of 2600 | | RSS | 98.2 → 1069.6 MiB, linear | 100 → 401.5 MiB, plateaus | | `external` | 3.6 → 76.5 MiB | 3.6 → 4.5 MiB | | `heapUsed` | 21.2 → 79.1 MiB | 21.2 → 27.4 MiB | Without the cleanup, RSS grows by a steady ~93 MiB per 300 aborted requests across rounds 2–8 (≈310 KiB per request, consistent with zlib's default deflate state plus per-stream buffers), and every unreleased stream is *still reachable after repeated forced GC* — permanent retention rather than GC lag. With the cleanup, all 2600 contexts are closed and RSS plateaus, with the residual difference from baseline being allocator retention rather than per-request growth. As a control, 200 fully-read responses issued into the same un-fixed process all closed normally, isolating mid-stream disconnects as the trigger. The issue also attributes the leak to a retained RSC element tree held via the `WeakMap` in `use-flight-response.tsx`. That part did not reproduce on canary: across 8000 aborted requests spanning dynamic renders, `redirect()`, `notFound()` and render throws, and 3000 full reads of the same 1.25 MB payload, post-GC heap stayed flat at ~29 MiB. The native `zlib_memory` line in the reporter's heap-snapshot diff was the actual cause. ## Verification - `pnpm test-start-turbo test/e2e/custom-server/custom-server.test.ts` and `pnpm test-dev-turbo test/e2e/custom-server/custom-server.test.ts` — covers `Content-Encoding: gzip` through a custom server, i.e. the code path being changed (46 and 45 passing) - `npx jest packages/next/src/server/lib` — 188 passing, including the 4 new cases - Manual: verified a gzipped response still decompresses byte-identical to the same response with `accept-encoding: identity` (1,250,721 bytes), with no errors or `MaxListenersExceededWarning` under sustained load - Manual: the before/after table above, re-measured against this branch's HEAD <!-- NEXT_JS_LLM --> Co-authored-by:Pete Hunt <239742+petehunt@users.noreply.github.com>
-
Hendrik Liebau authored
This moves the dev-mode Cache Components validation renders off the dev server's main thread onto a worker thread, so rapid navigation no longer starves the event loop. The worker crosses into the app-page bundle exactly once, calling a new `ComponentMod.routeModule.runValidationInDev` entry that rebuilds the render context, work store, and request store from a serializable snapshot and runs the whole validation there, so the client prerender and the user's client components resolve the single app-page React instance rather than a second copy. A thin worker shell (`dev-validation-worker.ts`) plus a single-worker pool (`dev-validation-worker-pool.ts`) load the user bundle via `loadComponents`, install code-frame support for CLI output, and forward the validation errors back as Flight bytes; the main thread only delivers them to the overlay through `sendErrorsToBrowser`. The snapshot, the globalThis-symbol handoff, and the shared error-delivery helpers live in their own modules. The dev server installs the worker when `experimental.devValidationWorker` is not `false`, and `runDevValidationInBackground` uses it when present, falling back to the in-process path otherwise. A one-slot `SharedArrayBuffer` propagates a supersede abort into the worker so a newer navigation cancels an in-flight validation. The runtime bundle gains an `app-worker` entry for the worker with the `build/swc` boundary externalized for the code-frame native binding, and `patch-error-inspect.ts` now backs its code-frame renderer with a globalThis symbol so all copies of the module share it across the thread. The synthetic `bench/dev-validation` benchmark navigates back-to-back, so every click lands inside the validation window — the worst case for main-thread contention. Browser-observed navigation TTFB in that window, worker vs in-process: | Route | Worker (p50/p95/max) | In-process (p50/p95/max) | | ------ | -------------------- | ------------------------ | | client | 19 / 24 / 27 ms | 40 / 66 / 7762 ms | | server | 42 / 45 / 46 ms | 122 / 158 / 252 ms | | sprite | 109 / 117 / 169 ms | 196 / 208 / 299 ms | The steady-state difference is only tens of milliseconds; the effect that matters is the tail. In-process, a navigation that collides with an in-flight validation render can stall for seconds (this run peaked at ~7.8s on the client route, and the peak varies run to run) because a staged render does not yield until it finishes; off-thread the main thread stays free and that stall disappears. Read these as an upper bound, not a speedup that generalizes. The work moved off-thread is the validation render's CPU — bounded, route-dependent, and free of IO — so it does not grow with the main render's cost. In an app whose main render is dominated by IO the same absolute saving is a small fraction of the request, and it only appears when a navigation lands in the brief validation window; at ordinary click speed it is largely invisible. This is a dev-only responsiveness improvement whose benefit varies widely with the app and the navigation pattern. As a follow-up, the validation work that still runs on the main thread could move to the worker as well. When the main render can't be reused for validation (for example after a cache miss), the validation re-renders on the main thread to produce its inputs, resuming from the Resume Data Cache (RDC) the main render already filled, and only then hands the resulting Flight chunks to the worker. A later iteration could run those renders inside the worker too, transporting the (serializable) RDC so the worker can resume from the filled caches rather than reading them back on the main thread. closes NAR-895
-
Hendrik Liebau authored
This adds `bench/dev-validation/`, wired as `pnpm bench:dev-validation`, which measures how much dev-mode Cache Components validation contends for the dev server's event loop during rapid navigation, and how much running it on a worker thread relieves that. It toggles `experimental.devValidationWorker` (added in the previous commit) to A/B the two configurations on the same build. Until the worker implementation lands the flag is inert and the A/B shows no delta. The fixture generates one route per family (`client`, `server`, `sprite`), each nested several layout segments deep under a `(routes)` route group. Validation renders a combined payload at every URL depth, so a deeper route means more validation work per navigation, which mirrors a realistically deep app rather than a single flat segment. The runner clicks a family's `<Link>` repeatedly, since navigating to the current route re-renders and re-validates it on every click. The routes carry no `instant` config because dev validation applies to page segments by default at the warning level. The three families isolate the client prerender, the Flight re-encode plus owner-stack work, and the Flight payload size, respectively. The signal is browser-observed TTFB taken from Playwright's own network timing, because it includes the time a request waits for the event loop while validation monopolizes it. We deliberately do not use the CLI's logged request durations: the dev server starts that clock inside the request handler, after the loop has already yielded to the request, so the queue wait is invisible to it. The runner prints each configuration's absolute TTFB (p50/p95/max) side by side rather than a ratio. The time the worker frees is the validation render's CPU, which is bounded, route-dependent, and does no IO, so a ratio would overstate a win that does not scale with total request time. Because the clicks are back-to-back the numbers are a worst case — navigations that land inside the validation window — and the `max` tail is the honest headline: it is the main-thread stall the worker removes.
-
Hendrik Liebau authored
<img width="428" height="179" alt="Screenshot 2026-07-24 at 22 42 04" src="https://github.com/user-attachments/assets/38478940-d23e-4faa-bd88-5758190be158" /> [Flakiness metrics](https://app.datadoghq.com/ci/test/runs?query=test_level%3Atest%20%40git.repository.id%3A%22github.com%2Fvercel%2Fnext.js%22%20%40test.name%3A%22enabled%20features%20in%20trace%20should%20denormalize%20inherited%20enabled%20features%20during%20upload%22%20%40test.type%3A%22nextjs%22%20%40test.status%3A%28%22fail%22%20OR%20pass%29&agg_m=count&agg_m_source=base&agg_t=count&fromUser=true&index=citest&start=1784320894753&end=1784925694753&paused=false) The `render-path` span is recorded when a request's response closes, which is too late for any flush other than the one the dev server performs while shutting down. The parent `next dev` process escalates to SIGKILL 100ms after signalling the child, and on a machine running eight test files at once the child does not reliably get scheduled to run its cleanup within that window, so the span never reached the trace file and the upload assertions failed. This change raises the budget for the test through `NEXT_EXIT_TIMEOUT_MS`, which was added alongside that timeout in #67165 so that it can be increased when the child's exit work matters more than a fast exit. The same approach is already used in `test/e2e/filesystem-cache/warm-restart-task-stats.test.ts`, where the timeout would otherwise cut off a Rust `on_exit` handler before it writes its task statistics. Both test cases previously guarded their request with a check for the existence of the trace file, which the dev server creates on its own once the first compile finishes. When that happened before the first test body ran, neither case issued a request and the trace file contained no `compile-path` or `render-path` span at all. The request and the shutdown now happen once in `beforeAll`, and the fixed 500ms sleep that followed the shutdown is replaced by a `retry` that waits for the spans the assertions depend on. --- <sub>Stack created with <a href="https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a href="https://gh.io/stacks-feedback">Give Feedback
💬 </a></sub> -
Hendrik Liebau authored
This is a behavior-preserving refactor of the dev-mode Cache Components validation, ahead of the change that moves it onto a worker thread. In-process behavior is unchanged. It narrows the context the validation functions require. `runValidationInDev` and its helpers (`validateStaticShell`, `warmupClientModulesForStagedValidation`, `validateStagedShell`, `validateInstantConfigs`) now take a `ValidationRenderContext` (a `Pick` of `AppRenderContext` plus the two `renderOpts` fields and the debug-channel flag they actually read) instead of the full render context, with `toValidationRenderContext` mapping the in-process and build-time callers. The worker cannot reconstruct a full `AppRenderContext` from a serialized snapshot, so narrowing the contract to what validation genuinely consumes is what lets the same code run there. It also separates computing the validation errors from delivering them. `runValidationInDev` now returns the errors instead of sending them to the dev overlay inline, and the caller `runDevValidationInBackground` delivers them via `logMessagesAndSendErrorsToBrowser`. The test-mode lifecycle markers and delay move into `runWithDevValidationLogging`, which brackets both the render and the delivery. When validation runs on the worker, the worker computes the errors but the main thread still delivers them (delivery needs the response object), so splitting the two halves is a prerequisite. Finally, it extracts the test-only validation lifecycle markers into a shared `dev-validation-events` module. The `<VALIDATION_MESSAGE>` wrapping and the event shape had been hand-rolled at each emission site in `app-render.tsx` and duplicated again in the test harness; they now live in one place as `formatValidationEvent` and an exported `ValidationEvent` union that the in-process emitters call and the test utilities import rather than redeclare. The worker emits the same markers through the same helper once it is added, so a single definition keeps every producer and the test parser in sync. Build validation's marker `requestId`, previously the numeric `Date.now()`, is stringified to fit the shared `string` type; it appears only in the logged marker payload, which nothing matches on, so this too is unobservable.
-
Hendrik Liebau authored
This adds the `experimental.devValidationWorker` boolean option: its type in `config-shared.ts` and its schema entry in `config-schema.ts`. The flag is the configuration seam for running development Cache Components validation on a worker thread rather than the dev server's main thread, which keeps the event loop responsive during rapid navigation. It is enabled by default, and setting it to `false` runs validation in-process, as an escape hatch to isolate a problem or fall back if the worker misbehaves. We land the flag on its own, ahead of the preparatory refactor, the benchmark, and the worker implementation that follow in the stack, so those changes can reference and toggle it. On its own the option is recognized by config validation but is not yet read anywhere. Because the flag is consumed only server-side in `next dev`, it needs no `define-env.ts` wiring for user-bundled code, nor `renderOpts` plumbing.
-
Hendrik Liebau authored
The settled output of a staged dev render and the inputs that dev Cache Components validation consumes were both modeled as extensions of a single shared interface that carried a nullable `syncInterruptReason: Error | null` alongside the render's accumulated chunks and stage timings. That flat shape let a sync-interrupted render and an uninterrupted one share one type even though their usable contents are disjoint, so every consumer had to read `syncInterruptReason` and treat the chunks as possibly present, and an interrupted validation input still carried a request store and debug channel that nothing downstream ever read. This change splits that shape into a proper discriminated union. `DevValidationInputs` becomes `ResolvedValidationInputs | SyncInterruptedStagedDevRender`, discriminated by the presence of `syncInterruptReason`: an uninterrupted render carries its artifacts, the request store, and the debug channel, while a sync-interrupted render carries only the interrupt reason (its debug channel is dropped at construction). A render's own settled output is a `StagedDevRenderResult` whose `outcome` is that same `StagedDevRenderArtifacts | SyncInterruptedStagedDevRender` union, with `hadCacheMiss` lifted onto the result rather than the outcome, because it is orthogonal to how the render ended (either kind can miss caches) and is consumed before the result is split into validation inputs. The render constructors drop the debug channel at the point of interruption, so `forwardErrorsFromWarmRender` no longer needs to, and the consumers that only ever handle a resolved render (`runValidationInDevImpl`, `validateStaticShell`, and the reuse path in `prepareValidationInputs`) take `ResolvedValidationInputs` directly. This is a behavior-preserving refactor.
-
Hendrik Liebau authored
In dev, a render that uses a request-time API inside `'use cache'` records an invalid dynamic usage error on its work store. This is an error in the render the user received, not a validation insight, yet it was forwarded to the dev overlay from inside `runDevValidationInBackground`, entangled with the validation lifecycle, and a separate non-validating code path forwarded the same error a second way. This change moves the forwarding, together with the `cacheReady()` wait that finalizes the error's verdict, out to the render's completion handler, where it runs once the render has settled regardless of whether the route validates. Validation becomes a pure consumer of the settled render: `runDevValidationInBackground` no longer reads or forwards the error, takes the settled render result rather than its promise, and is simply not scheduled when the render recorded such an error, since there is then nothing worth validating. Deferring the scheduling until the render has settled costs nothing, because validation already waits for the response to finish before it does any work, by which point the render result is always available. Consolidating the forwarding into one place at the render level disentangles this main-render concern from validation and prepares the ground for the upstack refactor that remodels the render-result types without the validation task reaching into them.
-
Marcos Hernanz authored
## What Derive implicit cache tags by scanning pathname slash boundaries incrementally instead of repeatedly rebuilding prefixes with `split`, `slice`, and `join`. The new loop emits exactly the same derived-tag array as the old helper, including the full-path prefix. The caller's existing `Set` continues to deduplicate that tag against `pathname` when they are equal. This PR's optimization is specifically the removal of repeated intermediate path arrays and prefix joins; it does not rely on changing deduplication semantics or tag order. Coverage includes root paths, `page` and `route` suffixes, missing leading slashes, repeated/trailing slashes, Unicode, malformed UTF-16, and already-encoded pathnames. ## Correctness The candidate was compared element-by-element with the original `split('/').slice(0, i).join('/')` implementation over **1,713,653 paths** on each of Node 20.9.0, Node 22.23.1, and Node 24.14.1: - 349,525 exhaustive strings of length 0–9 over a slash/ASCII alphabet; - every UTF-16 code unit: 65,536 cases; - every valid surrogate pair: 1,048,576 cases; - 250,000 deterministic randomized paths with Unicode, malformed surrogates, controls, reserved characters, suffix-like content, and arbitrary slash placement; - 16 targeted cases, including a one-million-character segment and a 1,024-segment path. All three runtime runs completed with **0 mismatches**. ## Performance Pinned CPU 4 on a 16-vCPU / 32-GiB Vercel DevBox. Each of 35 scenarios used 31 interleaved rounds, adaptive iterations, and two identical baseline lanes (A/A control). Scenarios cover depth 1–256, slash-dense paths, segment widths 1–512, suffix cases, no-leading-slash inputs, Unicode/malformed code units, and seeded shallow/medium/deep corpora. | Runtime | Scenarios improved | Seeded shallow | Seeded medium | Seeded deep | | --- | ---: | ---: | ---: | ---: | | Node 20.9.0 / V8 11.3 | 35/35 | **-77.11%** | **-82.59%** | **-92.69%** | | Node 22.23.1 / V8 12.4 | 35/35 | **-81.07%** | **-88.60%** | **-95.47%** | | Node 24.14.1 / V8 13.6 | 35/35 | **-80.98%** | **-89.00%** | **-95.88%** | No candidate p05–p95 interval crosses zero on any runtime. Selected Node 24 results: | Scenario | Median delta | p05–p95 | | --- | ---: | ---: | | Realistic root/suffix corpus | **-77.70%** | -78.02% to -77.22% | | Repeated/trailing slashes | **-77.88%** | -79.24% to -77.07% | | Unicode and malformed UTF-16 | **-63.49%** | -64.59% to -62.31% | | Depth 8, 4-char segments | **-83.14%** | -83.98% to -82.74% | | Depth 32, 4-char segments | **-92.48%** | -92.60% to -92.22% | | Depth 256, 4-char segments | **-98.77%** | -98.80% to -98.75% | | Depth 32, 512-char segments | **-97.02%** | -97.09% to -96.98% | Inspector heap-allocation sampling, five repeats (median sampled bytes): | Corpus | Baseline | Candidate | Change | | --- | ---: | ---: | ---: | | Realistic, 500k calls | 489,583,800 | 206,253,144 | **-57.87%** | | Shallow, 500k calls | 493,465,152 | 203,994,592 | **-58.66%** | | Deep, 20k calls | 843,885,312 | 112,216,736 | **-86.70%** | ### Alternative tested A split-once implementation that accumulated prefix strings also passed all 1.71M cases, but a direct 35-scenario interleaved comparison found the shipped `indexOf` implementation faster in **35/35** cases. Accumulation was 26.49% to 1,810.86% slower and sampled 47.5%/70.3%/280.8% more bytes on realistic/shallow/deep corpora. It was rejected. ### Production profile The original matched render-pipeline profile used 1,000 serial plus 10,000 concurrent-load requests: | Attribution | Baseline | Candidate | | --- | ---: | ---: | | Total sampled CPU | 20,534.6 ms | 20,461.6 ms | | Next runtime sampled CPU | 7,786.1 ms | 7,856.8 ms | | `implicit-tags.ts` | 54.1 ms (0.69%) | 41.4 ms (0.53%) | That is a **23.48% reduction** in source-attributed production CPU. A single load-throughput run improved 3.64%, but that is inside the workload's established 6.76% full range, so this PR does not claim a separately resolvable total-throughput improvement. ## Validation - `pnpm exec jest packages/next/src/server/lib/implicit-tags.test.ts --runInBand` — 12/12 passed - `pnpm prettier --check packages/next/src/server/lib/implicit-tags.ts packages/next/src/server/lib/implicit-tags.test.ts` - `pnpm eslint packages/next/src/server/lib/implicit-tags.ts packages/next/src/server/lib/implicit-tags.test.ts` - `pnpm --filter next types` - `pnpm --filter next build` - `pnpm build-all` — 18/18 tasks successful, including `@vercel/turbopack-next` checks - Correctly scoped Codex GPT-5.6 Sol xhigh review: clean, 0.98 correctness confidence - Correctly scoped Claude Opus 4.8 xhigh review: clean, 0.90 correctness confidence GitHub CI has 111 passing checks. The Windows integration job failed after `curl` received a connection reset while downloading Datadog tooling (exit 35); the aggregate `thank you, next` check reflects that infrastructure failure. No changed-file or implicit-tag test failed. --------- Co-authored-by:vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
-
Marcos Hernanz authored
## What - Replace repeated `Array.shift()` calls in the HMR affected-module breadth-first traversal with a monotonically increasing queue index. - Clear each consumed slot immediately so copied dependency chains can be collected during deep traversals. ## Why `getAffectedModuleEffects` can enqueue a wide set of parents when a shared dependency changes. Repeatedly shifting the queue moves the remaining array contents on every iteration, making broad invalidations increasingly expensive. Indexed reads keep traversal FIFO and make queue consumption linear. The slot clearing is important for deep graphs: it avoids retaining every processed item's copied `dependencyChain` until traversal returns. ## Benchmark Three independent 8-vCPU/16-GiB Vercel Sandbox workers ran Node.js 24.14.1 from exact commit `0950e8ae`. The balanced `A1/B1/B2/A2` benchmark mirrors this loop for one changed shared dependency imported by N root modules, including dependency-chain allocation. Each phase used three warm-ups and nine samples. | Affected parents | `shift()` median | Indexed median | Improvement | Speedup | Worker agreement | Max baseline A/A drift | |---:|---:|---:|---:|---:|---:|---:| | 1,000 | 0.160 ms | 0.089 ms | 45.81% | 1.85x | 3/3 | 9.91% | | 20,000 | 27.895 ms | 2.929 ms | 89.43% | 9.46x | 3/3 | 7.85% | | 50,000 | 164.960 ms | 7.342 ms | 95.52% | 22.33x | 3/3 | 1.21% | | 100,000 | 665.564 ms | 15.840 ms | 97.62% | 42.02x | 3/3 | 2.23% | The small-graph effect is intentionally modest; this targets very broad HMR invalidations in large applications. ## Validation - targeted Prettier: pass - targeted ESLint: pass - `pnpm --filter @vercel/turbopack-ecmascript-runtime check:nodejs`: pass - `CARGO_TARGET_DIR=/home/vercel-sandbox/next.js/target cargo check -p turbopack-ecmascript-runtime`: pass - GPT-5.6 Sol xhigh + Claude Opus 4.8 xhigh autoreview: clean after addressing a first-round dependency-chain retention finding (0 findings, correctness 0.99) The aggregate runtime TypeScript check remains blocked by an existing `runtime-utils.ts:239` `EsmExport` type mismatch. The identical `check:browser-dev-client` failure reproduces on the untouched baseline and is unrelated to this file. --------- Co-authored-by:
vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
-
- 24 Jul, 2026 20 commits
-
-
next-js-bot[bot] authored
-
dan authored
Improves development performance when we have a huge file with lots of functions (each of which gets its own copy of the sourcemap). The issue is due to `data:` sourcemaps, as foreseen in https://github.com/vercel/next.js/pull/81904. Node.js forever retains a parsed copy of a sourcemap per eval'd fake function, keyed by each function's unique `sourceURL`. There's also a bunch of CPU work that gets repeated. The fix is to switch to `file:` sourcemaps, which we can easily do in Turbopack in dev because all chunks have a `<chunk-name>.map` source map. We'll inject this behavior from `hot-reloader-turbopack.js`. # Test Plan That hyper slow example we've seen no longer takes 12s to render first route in dev: <img width="532" height="268" alt="Screenshot 2026-07-20 at 02 22 24" src="https://github.com/user-attachments/assets/31507ca8-f45c-4fd0-b895-c18f885476e4" /> Also, `vercel-docs` no longer OOMs when slowly navigating across a bunch of routes. (It still OOMs on fast bursts — to be investigated separately.) I see sourcemaps in: - Terminal - Instant Validation - Server Error - Client Error - Cache Error - Server HMR - Client HMR ---- <h1 id=wtf> Okay, but seriously, how does it work?</h1> I'm glad you asked... While working on this PR, I've learned a lot of trivia about sourcemaps and the tricks we do in React to make them work nicely across environments. I'm afraid I'll forget all of them so I wrote them down here. ## Basics A stack is made of frames. Frames can originate in different environments, and can look like `https://example.com/chunk.js` (browser) or `/Users/dan/layout.js` (CJS Node) or `file:///Users/dan/app/layout.js` (ESM Node), or something more exotic (`webpack://bundle.js` etc). You can see them by doing `new Error().stack`. However, these frames are not necessarily what the user *sees* in the stack. If the relevant script contained a reference to a sourcemap, the displayed frame is whatever the sourcemap says for that position. So this is how `https://example.com/bundle.js:1:2` can show up as `app/Button.tsx:5:10`. It means that `https://example.com/bundle.js` contains a sourcemapping URL to a sourcemap that says "this piece of code is actually from `app/Button.tsx`". ## Fake Frames Suppose we're in a browser, but the error contains some frames originally from the Server (in the RSC sense). If we just let the browser display them as is, a `/Users/dan/app/.next/server/chunk.js:1234:56` frame will show up in the browser. Which is fine but it wouldn't be clickable and obviously wouldn't display source code (because why would it). So we do a little trick. We eval a special empty function that's positioned right where the original frame was in the chunk (e.g. line 1234, char 56) by padding it with newlines and spaces. Inside that eval, we point at the *chunk's* sourcemap — the one that says "the code at 1234:56 is actually a function from `app/layout.js`". What this achieves is that in the stack you see `app/layout.js` (because the sourcemap says that's what this position is), and when you click on it, the contents of that server file is shown (because the sourcemap includes the original source text). Since our stub sits at exactly the position the real frame had in the chunk, the chunk's sourcemap gives the right answers for it. **So we've tricked the browser into displaying a frame with the server code.** (This was the feature that motivates all this.) Now, for all of this to work, we still need to give some name to the surrounding module during eval. In other words, our "fake" module is not a `file://` or `https://` or whatever. It's just a virtual eval'd thing that exists so that it can "sourcemap" down to the real server file, and we can splice those frames in the current environment's stacks. Let's give this module a URI like `about://React/Server/file:///Users/dan/app/.next/server/chunk.js?1`: - We want these stubs to be grouped separately away from people's eyes in the Source tab. They're not real code. - `Server` can be `Cache` or others instead, that's the React environment it represents - The `file://` part after that is the compiled file whose frame this stub is standing in for - The `?1` part at the end makes this stub module unique - We need that because every distinct frame (function and position) needs its own "empty file with a function" stub, and one file can appear in many frames. So we can't use the same URI or the browser will treat them as the same module. We'll call this `about://React/Server/file:///Users/dan/app/.next/server/chunk.js?1` thing a "virtualized" URL. To recap: it's the URI of a virtual eval'd module that is almost completely empty but has an empty function at just the right line, and a sourcemap that says "actually if you click on my frame, display `app/layout.js`". ## Browser Symbolication For the browser itself, the above is sufficient. The browser sees `about://React/Server/file:///Users/dan/app/.next/server/chunk.js?1` in the stack (spliced by React to mark a frame from another environment). But the user doesn't see this if they have sourcemaps on. This is because the browser loads the sourcemap that this module points to, and that sourcemap "makes it look" like the real `app/layout.js`. Illusion achieved. ## Where Does a Source Map Come From For the above to work, the virtual module generated by React needs to contain a `//# sourceMappingURL=` which points to the thing that lets it masquerade as the server module. React can't do this on its own since it shouldn't be reading files and may not have access to them anyway (at least not in the browser). So this is actually injected into React by the framework (the thing being injected is called `findSourceMapURL`). Next.js itself has multiple implementations of `findSourceMapURL`: - The version for the browser emits - `//# sourceMappingURL=<chunk-url>.map` for client sourcemaps - `//# sourceMappingURL=/__nextjs_source-map?filename=...` for server sourcemaps which loads it over HTTP - The version for Node.js emits - `//# sourceMappingURL=data:...` URI with the same sourcemap inline. React doesn't care. It just needs something to put into `//# sourceMappingURL=` of those virtual modules, and then hopefully the surrounding environment is actually able to resolve this. ## Why `data:` for Node.js? You might wonder why SSR points to sourcemaps with `data:` URIs instead of HTTP like the browser version. The answer is that we want to support debugging *Node.js process itself* with a Chrome debugger. And Node.js version of Chrome debugger does not load HTTP `sourceMappingURL`. It only supports `file:` or `data:`. Today we use `data:`. ## Terminal Symbolication What we have above is enough for browsers, where we use HTTP, and for Node.js Chrome debugger, where we currently use `data:`. They'll follow `sourceMappingURL` and grab the sourcemap when they need it. But we also show error stacks on *our own* surfaces, e.g. in terminal. So we need to replicate what the browser does. We need to resolve arbitrary frames (whether real ones like `/Users/dan/...` or `file:///Users/dan` — stuff from the current environment captured by V8 — or weird ones like `about://...`, which is stuff from an earlier environment like Server or Cache). We need to resolve them to source files like `app/layout.js` and such. For the browser (or for Node.js), this is easy because the runtime already "remembers" executing each module, and what the `sourceMappingURL` told it. However, *our own* terminal printing code is unaware of what happened inside Node.js. So we need to get creative: 1. For real Node.js frames from the current process like `/Users/dan/...` (CJS) and `file:///Users/dan` (ESM), there is no problem. If they have sourcemaps (e.g. Turbopack output), those are relative like `//# sourceMappingURL=foo.js.map`. Node.js reads and caches those when it loads each module, and `require('module').findSourceMap` gives us what it cached. 2. For virtual frames like `about://...`, we need to know what actual file it corresponds to. We could try to parse it out of the virtual frame itself, but actually we don't need to do that. **It turns out that we can simply ask the Node.js inline sourcemap cache: "give me the inline sourcemap you cached when evaluating this frame's module".** This works because Node.js already caches all sourcemaps from modules that have `data:` URIs as source map URL. So we just look into that map under the `about://...` key, and we can treat that `about://` key itself as opaque. Once we get that sourcemap, we can parse it and symbolicate the frame. ## The Problem **Okay, now we're finally getting to the point of this PR.** It turns out that it is actually expensive to use `data:` URIs for this. Worst of all, it's expensive in the happy case (when errors don't show up). Let's see why this is expensive. React's fake modules are evaluated not just for thrown errors, but for debug information (component stacks) that travels with JSX. So this has nothing to do with throwing or the cost of displaying an error. We're always materializing those frames. (Can we do that lazily? I'm not sure.) To materialize these frames, Node evaluates our fake modules — one per distinct frame that shows up in stacks. So a big file with 100 components appearing in stacks means 100 fake modules. Each of them includes the same `//# sourceMappingURL=data:...` URI carrying the entire sourcemap of the chunk that file was compiled into. So you can see why we have a problem: 1. A big original file with 100 components would produce 100 virtual modules 2. Each of the 100 virtual modules contains an identical `data:` with the sourcemap for the entire chunk 3. Node.js does not dedupe any work between `data:` URIs so they *each* get parsed 4. Worse, Node.js doesn't share memory between identical sourcemaps born from `data:` so they pile up in memory 5. Even worse, this memory is effectively never freed (the cached sourcemaps live as long as the eval'd modules, and React keeps the fake functions in a cache forever) That's why we saw 12 second slowdown on the start of one demo app with a huge number of icon sprites in one file. Basically, Node.js didn't anticipate that many different files may include an identical inline sourcemap, and so this case is very badly unoptimized. (We could plausibly send a fix for this but it would only affect those who upgrade.) So all of this isn't super great, and that's what we're trying to fix. ## The Fix: Just Use Files To reiterate, the problem we're solving is that a fake module with a huge `//# sourceMappingURL=data:...` has upfront evaluation cost, and we're potentially evaluating a lot of these modules. The obvious fix is to stop using `data:` URIs. But what other option do we have for symbolicating on the server? We can't use HTTP (like in the browser) because that would break debugging Node.js with Chrome. Our only options are `data:`... and `file:`. So let's try `file:`. But for that to work, we need the sourcemap to already exist on the disk. With webpack, we can't do this because our webpack setup doesn't write sourcemaps to disk (unless we make it, I guess). I'm not touching that in this PR. So webpack stays with suboptimal performance, and this fix doesn't improve it. But for turbopack, we can do this trivially. In dev, every first-party `chunk.js` compiled by Turbopack in the output already has a `chunk.js.map` next to it. So we just need to point our fake modules at *that* sourcemap that *already exists* on disk. Then Node.js has no per-module work to do at all — it simply ignores `file:` sourcemap URLs on eval'd modules instead of materializing them. Whoever actually needs the sourcemap later (the Chrome debugger, or our own terminal code) resolves it from disk, and all fake modules for one chunk point at the same single file. In other words, instead of this: - The version for Node.js emits `//# sourceMappingURL=data:...` URI with the same sourcemap inline. We want to do this: - The version for Node.js emits `//# sourceMappingURL=file:...` URI that points at the sourcemap on disk. **That's the `source-maps.ts` change in this PR.** We ask the bundler for a source map file first, and if the source map file exists, we return that (as a `file:` URI) instead of the `data:` URI. This fixes the memory issue and the 12 second slowdown. ## The Tricky Bits With the change above, debugging Node.js via Chrome debugger will "just work". It doesn't care whether the sourcemap is at a `data:` URI or a `file:` URI as long as the sourcemap actually exists. However, *our own* symbolication of terminal errors will break. Why is that? Recall how our terminal logic currently gets the sourcemap for every frame: >1. For real Node.js frames from the current process like `/Users/dan/...` (CJS) and `file:///Users/dan` (ESM), there is no problem. If they have sourcemaps (e.g. Turbopack output), those are relative like `//# sourceMappingURL=foo.js.map`. Node.js reads and caches those when it loads each module, and `require('module').findSourceMap` gives us what it cached. > >2. For virtual frames like `about://...`, we need to know what actual file it corresponds to. We could try to parse it out of the virtual frame itself, but actually we don't need to do that. **It turns out that we can simply ask the Node.js inline sourcemap cache: "give me the inline sourcemap you cached when evaluating this frame's module".** This works because Node.js already caches all sourcemaps from modules that have `data:` URIs as source map URL. So we just look into that map under the `about://...` key, and we can treat that `about://` key itself as opaque. The first case doesn't change — those keep working like before. But the second case is now broken. There's no entry corresponding to `about://...` URI in Node.js inline source map cache because *we did not use an inline sourcemap*. That was the whole point of switching to `file:`! It's how we get memory and CPU savings — Node.js no longer materializes them eagerly so they don't exist in any cache yet. **So we need to change the logic.** We need to treat `about://...` not as an opaque thing but as an encoded filename (it's inside — for example, `about://React/Server/file:///Users/dan/app/.next/chunk.js?1`). This lets us decode the filename out of it (strictly speaking, we get back `file:///Users/dan/app/.next/chunk.js` — React adds a `file://` prefix that decoding doesn't remove; more on that in the follow-ups). And knowing the JS file lets us get the map for it: the chunk itself was loaded by this process at some point, and Node.js read and cached the chunk's own sourcemap back then, so we look it up under the chunk's name. (If the chunk was never loaded in this process, Node.js has nothing, and we ask Turbopack for the map as a fallback.) **That's the `patch-error-inspect.ts` changes in this PR.** With this change, the terminal also gets symbolicated stacks after switching to `file:`. ## Follow-ups There's a couple of things I'm not super happy with: - It would be nice to fix this for webpack too? But maybe too risky or slow. I haven't tried. - Caching could be improved. There's no need to do duplicate work per each `?1` `?2` etc of the same file. I think there's a way to place caches so that we can still respect React's contract for "each frame may have its own map". - For some chunks with special names (e.g. `[root-of-the-server]` ones) whose sourcemaps are already loaded in Node.js memory in the same process (e.g. RSC frames transported into SSR world), we're no longer able to reuse the sourcemaps from Node.js memory, and instead have to fall back to asking Turbopack for them again. This is for two reasons: - We're no longer hitting the *inline* source map cache codepath because they're not inline. - We can't hit the Node.js *file* source map cache for them because we query them with wrong encoding: - Node.js file source map cache keys them with `pathToFileURL` encoding, like `file://...%5Broot-of-the-server%5D...` - Whereas devirtualizing `about://` React URL gives us `file://` URL with non-encoded content like `file://...[root-of-the-server]...` - The problem here is that `devirtualize(virtualize(absolutePath))` doesn't roundtrip. See https://github.com/react/react/pull/37105. - If it roundtripped, we would've gotten plain absolute `/...[root-of-the-server]...` and it would have been fine. - We can't fix this purely by tweaking the decoding on our side, because React prepends `file://` only when the filename starts with `/`, so from the decoded string we can't tell whether the original was an absolute path (CJS) that got prefixed or a real `file://` URL (ESM) that didn't. (We could try both interpretations against the cache — there are only two — but that's a follow-up.) - There's a related issue where an error travelling multiple layers (e.g. from Cache) gains `file://` on the second pass. I've had to add some defensive coding and a test for that. - This is not a huge deal because the Turbopack fallback saves us but I would've liked to fix this. I don't think they're land-blocking so I'll maybe follow up. --------- Co-authored-by:
Claude Fable 5 <noreply@anthropic.com> Co-authored-by:
Luke Sandberg <lukesandberg@users.noreply.github.com>
-
Andrew Clark authored
## Root cause `RouteCacheEntry` objects cycled through three hidden classes over their lifecycle, found by running `pnpm bench:deopt --scenario segment-cache`: (A) the pending object literal in `createDetachedRouteCacheEntry`, which did not declare `hasDynamicRewrite`; (B) that shape plus `hasDynamicRewrite` appended post-construction by `fulfillRouteCacheEntry`, a shape transition that also deprecates the original map; and (C) the two fulfilled-entry literals (`deprecated_requestOptimisticRouteCacheEntry` in `cache.ts` and the synthetic entry in `matchKnownRoute` in `optimistic-routes.ts`) which declare `hasDynamicRewrite` in a different key position, between `supportsPerSegmentPrefetching` and `renderedSearch`. Every property access on a route cache entry in the hot navigation/prefetch paths was therefore polymorphic. This PR pre-declares `hasDynamicRewrite: false` in `createDetachedRouteCacheEntry` at the same key position as the fulfilled literals, collapsing all three shapes into one hidden class, and moves the `hasDynamicRewrite: boolean` type declaration from `FulfilledRouteCacheEntry` to `RouteCacheEntryShared` to match. The `fulfilledEntry.hasDynamicRewrite = false` store in `fulfillRouteCacheEntry` is left in place; it is now an in-place store rather than a shape transition, and it re-clears the flag on re-fulfillment. ## Behavior neutrality The field is pre-initialized to `false` on pending/empty entries and semantics are identical: no runtime code reads `hasDynamicRewrite` from an unfulfilled entry, and there are no `in` checks, `Object.keys`, or `delete` operations on these entries — only property reads. `pnpm --filter=next types` passes with the field declared on the shared type. ## Verification Measured with `pnpm bench:deopt --scenario segment-cache` (fixture force-rebuilt against the patched build). The `hasDynamicRewrite` polymorphic IC cleared, along with ~24 entry-field polymorphic IC lines across `navigation.ts`, `optimistic-routes.ts`, `scheduler.ts`, and `cache.ts` (status, tree, canonicalUrl, renderedSearch, metadata, couldBeIntercepted, supportsPerSegmentPrefetching, staleAt, version, size). Total `ic-polymorphic` findings dropped from 84 lines to 60. Results were confirmed stable across a second run. Before/after `findings.txt` diff: ```diff 6,7d5 < high deopt-eager packages/next/src/client/components/segment-cache/scheduler.ts _heapIndex Insufficient type feedback for generic named access < high deopt-eager packages/next/src/client/components/segment-cache/scheduler.ts cancelPrefetchTask Insufficient type feedback for generic named access 8a7 > high deopt-eager packages/next/src/client/components/segment-cache/scheduler.ts isPrefetchTaskDirty Insufficient type feedback for generic named access 16d14 < info deopt-lazy packages/next/src/client/components/segment-cache/scheduler.ts pingSharedPartOfCacheComponentsTree (unknown) 29d26 < info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eR keys: push 37d33 < info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eg keys: canonicalUrl 47,51d42 < info ic-polymorphic packages/next/src/client/components/segment-cache/navigation.ts v keys: canonicalUrl < info ic-polymorphic packages/next/src/client/components/segment-cache/navigation.ts v keys: metadata < info ic-polymorphic packages/next/src/client/components/segment-cache/navigation.ts v keys: renderedSearch < info ic-polymorphic packages/next/src/client/components/segment-cache/navigation.ts v keys: status < info ic-polymorphic packages/next/src/client/components/segment-cache/navigation.ts v keys: tree 53d43 < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: hasDynamicRewrite 63d52 < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: couldBeIntercepted 65d53 < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: size 67,70d54 < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: staleAt < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: supportsPerSegmentPrefetching < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: tree < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: version 75,78d58 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts <anonymous> keys: status < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts <anonymous> keys: supportsPerSegmentPrefetching < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts <anonymous> keys: tree < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts F keys: metadata, tree 80,81d59 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts I keys: metadata < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts L keys: renderedSearch 86,87d63 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts e keys: 0 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts e keys: 1 93,94d68 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts j keys: status < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts j keys: tree ``` Two high-severity `wrong map` lines remain and are explicitly NOT claimed by this PR: the `cache-map.ts` `isValueExpired` line reads the intentionally 3-typed route|segment|bfcache map-value union, and the `optimistic-routes.ts` residual (now attributed to the `hasDynamicRewrite` read at 791:26) is a one-time map-deprecation deopt caused by in-place fulfillment generalizing null-initialized field types. The latter is tracked separately with a possible follow-up that fulfills entries via fresh literals instead of mutation. ## Tests - `test/e2e/app-dir/segment-cache/optimistic-routing-rewrite-detection-regression` (test-start-turbo): 3 passed - `test/e2e/app-dir/segment-cache/staleness` (test-start-turbo): 4 passed, 5 skipped (mode skips) ## Note on base branch
-
Andrew Clark authored
Found by `pnpm bench:deopt --scenario segment-cache` (V8 deopt/IC analysis of the client segment cache), with map-level IC evidence. Two related sources of megamorphism in the optimistic route matching path: (1) `String.prototype.split` returns arrays whose elements kind alternates between PACKED_ELEMENTS and HOLEY_ELEMENTS depending on internal fast paths, and `filter`/`slice` propagate the kind, so the arrays flowing through `matchKnownRoutePart` and `reifyRouteTree` had unstable maps, causing repeated "wrong map" eager deopts at the `slice` site in `matchKnownRoutePart` and the `join` site in `reifyRouteTree` (which runs once per tree node on every optimistic match); and (2) the private `ResolvedParams` map typed as `Map<string, string | string[]>` forced a polymorphic `Array.isArray`/`join` branch on every dynamic segment during reification. Semantics are preserved exactly. Catch-all param values are now joined into a single string at the moment they are resolved in `matchKnownRoutePart` instead of at read time in `reifyRouteTree` — the value was only ever read once and immediately collapsed to a joined string cache key, and the empty optional catch-all case writes `''`, which is identical to `[].join('/')`. The new `splitPathnameIntoParts` helper is byte-for-byte equivalent to `pathname.split('/').filter((p) => p !== '')`: empty tokens from leading, trailing, or consecutive slashes are skipped, but the parts array is built by pushing into an array literal so it always has a packed elements kind. Before/after `findings.txt` diff from the bench scenario: ```diff -high deopt-eager packages/next/src/client/components/segment-cache/optimistic-routes.ts matchKnownRoutePart wrong map -high deopt-eager packages/next/src/client/components/segment-cache/optimistic-routes.ts reifyRouteTree wrong map -info deopt-lazy packages/next/src/client/components/segment-cache/optimistic-routes.ts matchKnownRoutePart (unknown) -info deopt-lazy packages/next/src/client/components/segment-cache/optimistic-routes.ts reifyRouteTree (unknown) -info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eh keys: filter -info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eh keys: split -info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: join -info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: length -info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: slice -info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: filter -info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts g keys: split -info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts h keys: split +info ic-polymorphic packages/next/src/client/components/segment-cache/cache-key.ts u keys: charCodeAt +info ic-polymorphic packages/next/src/client/components/segment-cache/cache-key.ts u keys: length +info ic-polymorphic packages/next/src/client/components/segment-cache/cache-key.ts u keys: slice ``` Both high-severity wrong-map deopts in `optimistic-routes.ts` are gone (confirmed across two independent after-runs); the remaining new lines are info-level string-receiver ICs inside the splitter helper. Total ic-polymorphic findings dropped from 90 to 80. Tests (all passing, `test-start-turbo`): - `test/e2e/app-dir/segment-cache/optimistic-route-cache-keying-regression` — 1 passed - `test/e2e/app-dir/segment-cache/optimistic-routing-parallel-slot-catchall-regression` — 1 passed - `test/e2e/app-dir/segment-cache/encoded-slash-params` — 2 passed -
Andrew Clark authored
### Root cause Parallel route slot names are app-defined, so a `RouteTree.slots` stored as a plain object has an unbounded set of hidden classes: every distinct combination of slot names (`{children}`, `{children, side}`, ...) produces a different shape. Keyed access over these objects makes the inline cache megamorphic. This was the single `ic-megamorphic` finding reported by `pnpm bench:deopt --scenario segment-cache`, at the keyed store in `convertTreePrefetchToRouteTree` (`cache.ts:1531`, keys `children`, `side`). This PR converts `RouteTree.slots` from `{ [parallelRouteKey: string]: RouteTree }` to `Map<string, RouteTree>`. All reads, writes, and iterations over RouteTree slots now go through monomorphic `Map` method calls, and iteration order is preserved (Map iterates in insertion order, matching plain-object string-key order). ### Scope This was an approved design decision: `RouteTree` is an in-memory-only structure, so only it changes. `CacheNode.slots` (spread into JSX props) and the wire formats (`TreePrefetch.slots`, `FlightRouterState[1]`) remain plain objects; the existing conversion functions bridge them into and out of the Map. ### Before/after findings diff ```diff --- bench/deopt/artifacts/slots-map-before/findings.txt +++ bench/deopt/artifacts/slots-map-after/findings.txt @@ -high ic-megamorphic packages/next/src/client/components/segment-cache/cache.ts e keys: children, side +high ic-megamorphic packages/next/src/client/components/segment-cache/scheduler.ts e keys: children, side @@ +info deopt-dependency-change packages/next/src/client/components/segment-cache/scheduler.ts pingSharedPartOfCacheComponentsTree dependent prototype chain changed +info deopt-eager packages/next/src/client/components/segment-cache/scheduler.ts _heapIndex Insufficient type feedback for generic named access +info deopt-eager packages/next/src/client/components/segment-cache/scheduler.ts cancelPrefetchTask Insufficient type feedback for generic named access +info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eR keys: push ``` The targeted finding at `cache.ts:1531` is cleared. The remaining megamorphic site (stable across two runs) is `scheduler.ts:1068:23` in `pingSharedPartOfCacheComponentsTree` — the keyed load `oldTreeChildren[parallelRouteKey]`, where `oldTreeChildren` is `FlightRouterState[1]`, i.e. the wire-format plain object that is intentionally out of scope for this change. That access existed before this PR; previously the `for...in` loop key qualified the sibling load for V8's fast enum-cache path, and with Map iteration keys it now surfaces as a generic keyed load. Eliminating it would require changing the `FlightRouterState` children format, which is a separate decision. The new info-level lines are one-time warm-up/prototype-registration deopts from the introduced `Map` usage, not steady-state IC misses. ### Tests - `test/e2e/app-dir/segment-cache/basic` (start-turbo): 10 passed, 1 skipped - `test/e2e/app-dir/segment-cache/optimistic-routing-parallel-slot-catchall-regression` (start-turbo): 1 passed - `test/e2e/app-dir/segment-cache/cached-navigations` (start-turbo): 16 passed - `pnpm --filter=next types` passes (also re-run after rebasing onto canary) -
Andrew Clark authored
The segment cache's `RouteTree` objects were being created with two different hidden-class families: the two object literals returned by `reifyRouteTree` in `optimistic-routes.ts` listed their keys in a different order (`slots`, `prefetchHints`, `isPage`, `varyPath` last) than every other `RouteTree` constructor site in `cache.ts` (`varyPath`, `isPage`, `slots`, `prefetchHints` last). In V8, object literals with different key orders get different hidden classes (maps), so every code path that touches both optimistically-reified trees and server-derived trees saw polymorphic shapes. Found with `pnpm bench:deopt --scenario segment-cache` (the V8 deopt detection tooling from the base branch). This change is behavior-neutral: it only reorders the keys in the two `reifyRouteTree` object literals to match the canonical order used by `cache.ts`. No values, types, or logic change. With all `RouteTree` literals collapsed to one hidden class, the fix eliminates the polymorphic `RouteTree`-field inline caches: 22 findings removed across `optimistic-routes.ts`, `scheduler.ts`, `cache.ts`, and `vary-path.ts` in the before/after diff below (keys `requestKey`/`segment`/`refreshState`/`prefetchHints`/`slots`/`isPage`/`varyPath`). Note: the two remaining `wrong map` deopts at `optimistic-routes.ts:904` and `scheduler.ts:1058` are different object families — resolved-param values (string vs string[] at `newValue.join`) and `FlightRouterState` tuples (`oldTree[1]`) respectively — and are tracked separately. This PR does not claim to fix them. Before/after `findings.txt` diff (`bench:deopt --scenario segment-cache`, after run with `--force-build`): ```diff 9a10 > high ic-megamorphic packages/next/src/client/components/segment-cache/cache.ts eA keys: done, value 26,27c27 < info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eA keys: done, value < info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts e_ keys: varyPath --- > info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eR keys: push 35d34 < info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts eg keys: requestKey 38d36 < info ic-polymorphic packages/next/src/client/components/segment-cache/cache.ts q keys: varyPath 51d48 < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: isPage 54,57d50 < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: prefetchHints < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: refreshState < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: requestKey < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: segment 59d51 < info ic-polymorphic packages/next/src/client/components/segment-cache/optimistic-routes.ts e keys: slots 71d62 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts <anonymous> keys: prefetchHints 76d66 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts F keys: prefetchHints 79,86d68 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts M keys: prefetchHints < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts M keys: segment, 0 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts M keys: slots < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts e keys: prefetchHints < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts e keys: segment < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts e keys: segment, 0 < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts e keys: slots < info ic-polymorphic packages/next/src/client/components/segment-cache/scheduler.ts j keys: prefetchHints 93,94d74 < info ic-polymorphic packages/next/src/client/components/segment-cache/vary-path.ts g keys: isPage < info ic-polymorphic packages/next/src/client/components/segment-cache/vary-path.ts g keys: varyPath ```
-
Andrew Clark authored
`VaryPath` nodes are created and traversed on a very hot path in the segment cache, so their object shape matters for performance. `isRootParam` was optional: most nodes left it undefined while a few set it, so nodes had inconsistent shapes. That prevents V8 from sharing a single hidden class across them and deopts the cache hot paths. This makes `isRootParam` a required boolean, always set (`false` for structural and search param nodes), so every `VaryPath` node has the same shape and these paths stay monomorphic.
-
Aurora Scharff authored
## What Expands the [Single-Page Applications guide](https://nextjs.org/docs/app/guides/single-page-applications): - Adds a full **TanStack Query** section (server prefetch + `dehydrate` + client read), alongside the existing SWR and `use()` + Context patterns - Makes this guide the **canonical home for the `use()` + Context pattern**, so it is no longer duplicated across the docs (fetching-data keeps only the `React.cache` reuse and links here) - Rewrites the mutations section around one shared reducer with `useActionState` + `useOptimistic` - Links a companion runnable demo for every example, and modernizes the examples (typed `PageProps`/`LayoutProps`, `useSuspenseQuery` vs `useQuery` guidance, forms/server-actions related guides) ## Why The guide was outdated and thin on runnable examples, had no real TanStack Query coverage, and the context + `use()` pattern was duplicated across several guides. ## How Each section maps to a runnable demo route. The context pattern is centralized here as the single source of truth, with fetching-data, streaming, and authentication linking to it. Docs-only.
-
Aurora Scharff authored
docs: navigation interrupts after streaming has started (notFound, forbidden, unauthorized) (#95851) Adds a "Calling `x()` after streaming has started" example to the `notFound`, `forbidden`, and `unauthorized` references. - The check lives in the data-access function that loads the data, inside a `<Suspense>` boundary, so the page shell keeps streaming (blog post 404, account 401, admin projects 403). - Documents the status-code trade-off: the interrupt fires after headers are sent, so the response is a `200`; a `loading.tsx` is part of the stream, not a way around it; `instant = false` opts the route out of the shell for a real status code. - Links the authentication guide's DAL section instead of re-teaching it, plus a good-to-know on floating promises never rendering the UI. Docs-only.
-
Aurora Scharff authored
## Why Follow-up to feedback on the 16.3 partial-prefetching docs. The blog's "Fewer requests and lower bandwidth from visible Links" is an automatic, framework-level benefit, not a dev-facing knob, yet the prefetching docs still lead with the pre-Cache-Components model and never explain the shared-shell behavior that produces it. ## What changed - **`getting-started/linking-and-navigating`**: added an opt-in Cache Components callout to the prefetching section. `<Link>` prefetches a per-route App Shell, and many links to the same route reuse one shell, so a page with many links makes fewer prefetch requests. The default (non-Cache-Components) model description is unchanged. - **`guides/prefetching`**: restructured into two halves: - **What Next.js prefetches automatically** (static vs. dynamic, automatic prefetch, the App Shell model, scheduling, client cache) - **Controlling prefetching** (manual, hover, extend/eject, disable) Promoted and expanded the Cache Components / App Shell section as the home for the shared-shell / fewer-requests story, and scoped the legacy `staleTimes` tables to non-Cache-Components apps. All content-bearing anchors are preserved (including `#extending-or-ejecting-link`, the only one linked from other docs). Prose swept against the Vercel technical writing style guide. Docs-only. Related: DOC-6496.
-
Aurora Scharff authored
### What? Fix the skill install command in the view transitions guide. ### Why? The skill's registered name is `vercel-react-view-transitions` (the repo directory is `react-view-transitions`), so the documented `npx skills add vercel-labs/agent-skills --skill react-view-transitions` fails to resolve the skill. ### How? Use the verified command (`npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-view-transitions`) and align the heading, link text, and agent prompt with the real skill name. The directory link is unchanged.
-
Josh Story authored
Building on top of @agadzik work (see first commit) Adds prerender route metadata to help downstream consumers understand the nature of build-time prerenders We break down prerender taxonomy as follows routeType describes what the prerender serves: * `route`: a non-UI endpoint, such as a Route Handler. * `page`: a page whose route parameters are fully known. * `shell`: a reusable PPR shell for a parameterized page. * `fallback`: a fallback that may serve or specialize additional parameter values. response describes how complete the static response is: * `complete`: the prerender contains the completed response. * `initial`: an initial response is available, but the page UI is incomplete; in practice this applies to partially prerenderable UI routes. * `empty`: there is no initial static response to send. compute describes the request-time work required: * `static`: no request-time server compute is needed. * `resuming`: request-time compute resumes from the static response. * `blocking`: the initial response is blocked until request-time compute starts, but it may stream while that compute continues. `htmlSize` reports the byte size of prerendered HTML when the output has HTML. The taxonomy is included only on a prerender group’s canonical primary output—the HTML output for pages or the response output for Route Handlers—and is omitted from secondary RSC and segment-data outputs. --------- Co-authored-by:agadzik <andrew.gadzik@vercel.com>
-
Tim Neutkens authored
## Summary - Extract the invariant app-page handler into a shared runtime module while keeping each generated route entry as a small wrapper. - Keep the `interopDefault` binding in the route wrapper because the injected Turbopack metadata loader tree references it, and pass the same binding into the shared runtime. - Add a focused 14-route navigation benchmark with static metadata coverage. ## Why Turbopack gives every generated app-page entry a route-specific identity because its loader tree, page name, pathname, and module hooks are injected into the template. This caused the full app-page handler to be analyzed independently for every route. A clean native trace of the benchmark shows app-page analysis CPU falling from 1,619.39 ms across 14 route copies to 153.92 ms total across 14 small wrappers plus one shared runtime, a 90.5% reduction. Concurrency-corrected analysis time falls from 181.63 ms to 97.87 ms. The post-change fixture also includes a static icon to cover the injected metadata loader binding. ## Verification - `pnpm test-dev-turbo test/e2e/app-dir/metadata-icons/metadata-icons.test.ts` - `pnpm test-start-turbo test/production/adapter-config/adapter-config-export.test.ts` - `pnpm test-dev-turbo test/development/app-dir/app-page-entry-prefetch-performance/app-page-entry-prefetch-performance.test.ts` - `pnpm test-dev-webpack test/development/app-dir/app-page-entry-prefetch-performance/app-page-entry-prefetch-performance.test.ts` - Clean native reproduction: the metadata suite failed with `ReferenceError: interopDefault is not defined` before the binding fix and passed all 9 cases afterward. <!-- NEXT_JS_LLM -->
-
Jiwon Choi authored
### Why? VS Code passes a maximum hover length and verbosity level to TypeScript's `getQuickInfoAtPosition` API when a user expands a hover. The Next.js TypeScript plugin intercepted that call and forwarded the file name and position, dropping the remaining arguments. The plugin also replaced TypeScript's `QuickInfo` object when it added config documentation, which discarded native fields such as `canIncreaseVerbosityLevel`. As a result, hovers for Next.js config exports could not expand and lost native type information. This supersedes #86290 with a narrower behavior change. The plugin preserves native `QuickInfo` when it adds documentation to valid config values and config identifiers. Invalid config values keep the existing synthesized override, and hovers inside function initializers retain TypeScript's existing behavior. x-ref: https://github.com/microsoft/vscode/issues/232685#issuecomment-3484167019 | Before | After | |--------|-------| | <img width="1656" height="390" alt="Config hover without expandable metadata" src="https://github.com/user-attachments/assets/ed39a851-7096-448b-bffe-55c5320c1713" /> | <img width="1668" height="384" alt="Config hover with expandable metadata" src="https://github.com/user-attachments/assets/0a3a0cbc-5c75-4b6f-90fc-bbcef028d06b" /> | ### How? The plugin forwards all QuickInfo arguments to TypeScript and passes the native result into the config hover rules. For valid config values and identifiers, those rules copy the native `QuickInfo` fields and append the Next.js documentation. They synthesize the existing fallback when TypeScript returns no QuickInfo. Focused tests cover argument forwarding, metadata preservation, missing native QuickInfo, invalid config values, and function config boundaries. ### Test plan Open a minimal Next.js app in Cursor with workspace TypeScript 6.0.2 and the package built from this PR. Hover `export const metadata: Metadata`, then select the expansion control. The hover expands from `Metadata` to its full property type while the Next.js config documentation and link remain visible. <!-- NEXT_JS_LLM -->
-
Sam Poder authored
Imports the tests that Webpack uses for CJS tree-shaking. One test suite is skipped `deep-reexports`, that's because we don't support that deep of analysis at the moment and we just bail. WIP because after landing this stack I will work on improving this. I did have to make some edits to the tests, a summary is below (courtesy of Claude): ``` 1. Stripped ?query request suffixes (all cases). Webpack uses require("./x?1") / ?2 to force distinct module instances. Turbopack shares one instance across require sites and aggregates usage, so the queries were removed (require("./x")). The behavioral assertions hold on a shared instance. 2. Distinct copies where per-instance semantics are genuinely required. A few cases actually depend on separate instances, so we replaced the query with real duplicate files: - mutate → module-1.js / module-2.js (so mutating one import doesn't leak into the other). - reexports → add-to-counter-1/2/3.js (the counter must increment 3×). - reexports-define-property → add-to-counter-1/2.js. 3. Removed __resourceQuery (webpack module-query magic — undefined in turbopack). In reexports and reexports-define-property: require("./m" + __resourceQuery) → require("./m"), and the dynamic dispatch module reexport.js (require("./" + __resourceQuery.slice(1))) was split into static reexport-direct.js / reexport-indirect.js. 4. Commented out __webpack_exports_info__ / usedExports assertions. Webpack exposes per-export usage introspection (x.usedExports, __webpack_exports_info__.x.used) that turbopack doesn't populate for CJS. Those specific assertions were commented (the real behavioral checks kept) in: require-member-access, require-member-access-deferred, require-destructuring, this-in-exported-function(-modern), reexport-require-binding, mutate, cjs-to-esm. 5. Case-specific rewrites. - cjs-to-esm — dropped the require.cache[require.resolve(...)].exports comparison (webpack runtime introspection). - namespace — changed expect(await import(x)).toBe(require(x)) (object identity) to assert the observable exports (ns.abc, ns.default); turbopack's import() yields an exotic Module namespace, never the same/deep-equal object as require(). 6. mjs removed entirely — built on __resourceQuery + per-query instances + .js/.mjs interop divergence; can't even evaluate in turbopack and tests behavior turbopack doesn't share. ``` All tests should be passing. -
Sam Poder authored
This PR adds support for `turbopackRemoveUnusedImports` in CJS modules. If modules are side-effect free and their imports are unused we do the following re-writes: ``` require('./pure') → 0; console.log('x') console.log('x') ``` ``` const x = require('./pure') → const x = 0 ``` ``` const dead = require('./pure'), keep = 'v' → const dead = 0, keep = 'v' ``` ``` const {} = require('./pure') → const {} = 0 ``` ``` if (cond) require('./pure') → if (cond) 0; ``` SWC should then drop the 0. -
Sam Poder authored
This PR introduces a new method `analyze_require_usage` that analyzes how something imported with `require()` is used. It has two passes: one catches simple things like `const { a } = require(...)` and `require(...).foo`, the next one then handles if you import using `const x = require(...)`. This then gets populated into `export_usage_info`, this will expand the set of exports we can drop through https://github.com/vercel/next.js/pull/95716. -
dan authored
Not sure if there's any downside to this. Currently, there are situations when a browser requests something in a particular format: - Favicons - Manifest icons - `<img>` with broken `src` - Wrong `<link>`s - `new Worker()` These requests have a `Sec-Fetch-Dest` header which can definitely exclude things that can't be HTML. My proposal is to not return the HTML for them (even in dev) so that this doesn't waste time in case rendering the root layout is slow or expensive. Less work for the server, whether dev or prod. I believe this was happening in dev, and in prod if rendering `not-found` requires something dynamic (e.g. in the root layout). And for static self-hosted, I believe it would respond with static HTML. After this change, we don't render the HTML. ## Before Image in manifest hits the real `/not-found` route and runs application code: <img width="1055" height="639" alt="Screenshot 2026-07-19 at 00 23 01" src="https://github.com/user-attachments/assets/869f85f8-a009-4266-a345-74e3342adb41" /> Notice 404 at the end with 2 seconds in application code. ## After Image in manifest is still 404 but doesn't hit any app code. <img width="1033" height="696" alt="Screenshot 2026-07-19 at 00 21 17" src="https://github.com/user-attachments/assets/3a1817b4-f050-45c0-93ca-0507cf9de803" /> It's maybe a bit weird it doesn't show in the terminal log. In that sense it's like `/_next/static/` because it's handled at an earlier layer. Maybe we could still log it but it would have to happen from a different place, and also breaks consistency, so I opted with keeping it hidden. --- I can't see any coherent arguments for why this should reach the app render so this should be OK?
-
dan authored
Fixes a flurry of requests when doing server HMR. To reproduce the issue, create a server component imported from multiple routes: - Route `/a` imports that component - Route `/b` imports that component - Route `/c` imports that component - (...and so on...) Then edit that server component. Expected: one request in terminal per open tab. Actual: a flurry of requests. There's two separate causes for the flurry of requests: - The "server component updated" messages were emitted once per already-compiled route, so a single tab would receive a flurry of messages one right after another, and process them all. - Also, the `debounce` for these messages is broken (it always fires instead of delaying) due to a wrong condition inside it. So if we tried coalescing messages by key, we'd still see multiple requests per tab. - We should probably fix `debounce` but that's more risky because I don't know if either existing caller could rely on the bug. Luckily, for the fix below this doesn't matter. Anyway, to get the desired behavior (one refresh per page), we switch to expressing server component changes as a final message that gets sent at the end of the update using a dirty flag. Then we don't need to worry about how they get deduped or how many of them gets received. There are probably other ways to factor this but this one seemed fine to me. ## Before A flurry of requests. https://github.com/user-attachments/assets/337183e9-6fe2-4633-858d-6c1db6779618 ## After One request per open tab. https://github.com/user-attachments/assets/3543619e-7ab3-4b74-bbdf-2151e16e2c2b --------- Co-authored-by:
Claude Fable 5 <noreply@anthropic.com>
-
Sam Poder authored
Previously, code such as: ``` export { foo } from "bar" ``` Would contribute to a module's exports (we export foo). However, it would not contribute to our tracking of imports from "bar". Therefore we would fall back to the default import usage: https://github.com/vercel/next.js/blob/c0a7b91becb33490bf412d02bbf09ebaa7216083/turbopack/crates/turbopack-ecmascript/src/references/exports.rs#L140 ```rust pub enum ImportUsage { #[default] TopLevel, Exports(FrozenSet<RcStr>), } ``` We would therefore not tree-shake. This is rarely a problem with normal imports / exports because they support following reexports and this is enabled by default in Turbopack. However, async imports do not support following reexports. In https://github.com/vercel/next.js/issues/95698, the import of the Viem chain definitions is an async-imported module: <img width="796" height="81" alt="Screenshot 2026-07-20 at 5 47 43 pm" src="https://github.com/user-attachments/assets/2fc46711-469f-4f28-8369-9c1ea01b808d" /> Closes https://github.com/vercel/next.js/issues/95698 I looked at the reproduction from the original issue, and this was the result: ``` Client graph contains 11/712 viem chain definition files. Not reproduced; missing 701 definitions. ``` Yay!
-
- 23 Jul, 2026 1 commit
-
-
next-js-bot[bot] authored
-