1. 25 Jul, 2026 19 commits
    • next-js-bot[bot]'s avatar
      v16.3.0-canary.97 · 367e5215
      next-js-bot[bot] authored
      367e5215
    • Pete Hunt's avatar
      fix(sandbox): release one-shot timeout ids after they run (#96161) · d2ee326a
      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: 's avatarBerry Kim <wlsdud40@gmail.com>
      Co-authored-by: 's avatarDan Abramov <dan.abramov@gmail.com>
      d2ee326a
    • dan's avatar
      Fix dev overlay symbolication for project paths needing percent-encoding (#96221) · b51ca60f
      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: 's avatarClaude Fable 5 <noreply@anthropic.com>
      b51ca60f
    • dan's avatar
      [internal] Add a skill for benching changes in a sandbox (#95943) · 1a028f7f
      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: 's avatarClaude Fable 5 <noreply@anthropic.com>
      1a028f7f
    • Hendrik Liebau's avatar
      Run dev validation in process when using Webpack (#96219) · e1fbb180
      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.
      e1fbb180
    • Hendrik Liebau's avatar
      Read chunk source maps from disk in the dev validation worker (#96218) · 4bfd5c71
      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.
      4bfd5c71
    • Hendrik Liebau's avatar
      Retry the source map lookup with a plain path (#96215) · c1617ded
      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.
      c1617ded
    • Hendrik Liebau's avatar
      Pass fallback params to the dev validation worker as maps (#96210) · e73504e9
      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.
      e73504e9
    • dan's avatar
      [sourcemaps] Reuse source map payloads and consumers across stack frames (#96198) · dcf242a1
      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: 's avatarClaude Fable 5 <noreply@anthropic.com>
      dcf242a1
    • Pete Hunt's avatar
      fix: release compression stream when client disconnects mid-response (#96173) · 770f1577
      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: 's avatarPete Hunt <239742+petehunt@users.noreply.github.com>
      770f1577
    • Hendrik Liebau's avatar
      Run Cache Components dev validation on a worker thread (#96153) · 3c4afc1a
      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
      3c4afc1a
    • Hendrik Liebau's avatar
      Add a benchmark for dev Cache Components validation on a worker thread (#96152) · 59cc6420
      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.
      59cc6420
    • Hendrik Liebau's avatar
      [test] Unflake the `enabled-features-trace` test suite (#96175) · 62084e3f
      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>
      62084e3f
    • Hendrik Liebau's avatar
      [refactor] Prepare dev validation for running on a worker thread (#96151) · 954eabec
      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.
      954eabec
    • Hendrik Liebau's avatar
      Add the `experimental.devValidationWorker` config flag (#96150) · 488710b1
      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.
      488710b1
    • Hendrik Liebau's avatar
      [refactor] Model dev validation render outputs as a discriminated union (#96149) · 69801af7
      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.
      69801af7
    • Hendrik Liebau's avatar
      Forward dev invalid dynamic usage errors from the render, not validation (#96148) · 96d87715
      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.
      96d87715
    • Marcos Hernanz's avatar
      Optimize implicit cache tag derivation (#96120) · 779fbad9
      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: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
      779fbad9
    • Marcos Hernanz's avatar
      Avoid quadratic HMR queue shifts (#96137) · d5cc1e12
      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: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
      d5cc1e12
  2. 24 Jul, 2026 20 commits
    • next-js-bot[bot]'s avatar
      v16.3.0-canary.96 · 4a432e4d
      next-js-bot[bot] authored
      4a432e4d
    • dan's avatar
      [sourcemaps] Use file: sourcemaps for Turbopack to improve dev performance (#95946) · 740264b3
      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: 's avatarClaude Fable 5 <noreply@anthropic.com>
      Co-authored-by: 's avatarLuke Sandberg <lukesandberg@users.noreply.github.com>
      740264b3
    • Andrew Clark's avatar
      Give RouteCacheEntry a single hidden class across its lifecycle (#96164) · e2373498
      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
      e2373498
    • Andrew Clark's avatar
      Keep optimistic-route param handling monomorphic (#96169) · d8b6ae9c
      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
      d8b6ae9c
    • Andrew Clark's avatar
      Store RouteTree slots in a Map to keep slot access monomorphic (#96168) · 2d2f501f
      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)
      2d2f501f
    • Andrew Clark's avatar
      Make reifyRouteTree object literals match the canonical RouteTree key order (#96162) · c4ce0c9e
      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
      ```
      c4ce0c9e
    • Andrew Clark's avatar
      Keep VaryPath monomorphic by making isRootParam required (#96122) · aa13f252
      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.
      aa13f252
    • Aurora Scharff's avatar
      docs: expand and modernize the Single-Page Applications guide (#95860) · 6fd889b9
      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.
      6fd889b9
    • Aurora Scharff's avatar
      docs: navigation interrupts after streaming has started (notFound, forbidden,… · 0be0ebe5
      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.
      0be0ebe5
    • Aurora Scharff's avatar
      docs: reframe prefetching around automatic vs. controllable behavior (#95896) · b79052e0
      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.
      b79052e0
    • Aurora Scharff's avatar
      docs(view-transitions): fix the skill install command (#96142) · 2a25442b
      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.
      2a25442b
    • Josh Story's avatar
      Include additional prerender metadata about build-time routes (#96080) · 8d6c076d
      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: 's avataragadzik <andrew.gadzik@vercel.com>
      8d6c076d
    • Tim Neutkens's avatar
      Optimize app page entry analysis (#96058) · 3a48dd6a
      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 -->
      3a48dd6a
    • Jiwon Choi's avatar
      [ts-plugin] Preserve TypeScript quick info metadata (#95863) · 26824378
      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 -->
      26824378
    • Sam Poder's avatar
      [turbopack] Import Webpack's tests for tree-shaking (#95811) · 29b39663
      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.
      29b39663
    • Sam Poder's avatar
      [turbopack] Drop dead `require()` calls (#95718) · eb7beb59
      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.
      eb7beb59
    • Sam Poder's avatar
      [turbopack] Track usage of modules imported with `require()` (#95717) · 1f04d8ff
      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.
      1f04d8ff
    • dan's avatar
      Return plain text 404 for non-document requests to unknown paths (#95930) · 0950e8ae
      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?
      0950e8ae
    • dan's avatar
      [RSC HMR] Fix a flurry of refetches when a editing component imported from many routes (#96102) · b1713c85
      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: 's avatarClaude Fable 5 <noreply@anthropic.com>
      b1713c85
    • Sam Poder's avatar
      [turbopack] Track re-exports in `import_usage` inside of `compute_import_usage` (#95989) · 326fc900
      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!
      326fc900
  3. 23 Jul, 2026 1 commit