1. 29 Jun, 2026 18 commits
    • next-js-bot[bot]'s avatar
      v16.3.0-canary.71 · dff50cc7
      next-js-bot[bot] authored
      dff50cc7
    • Sam Poder's avatar
      [turbopack] Discover service workers in the Turbopack analyzer (#94923) · 0d1dc023
      Sam Poder authored
      This PR is the PR that "turns on" the service worker feature, this is
      because in the analyzer we are now looking for code like:
      
      ```
      await navigator.serviceWorker.register(new URL('../lib/service-workers/1.js', import.meta.url), ...)
      ```
      
      And transforms it into registering the URL that Next.js will now serve
      based on scope.
      
      URL scheme is:
      
      ```
      scope: "/" -> `sw.js`
      scope: "/offline/mode" -> `sw-offline-mode.js`
      ```
      
      etc.
      
      It also inserts the `ServiceWorkerEntryModule`s so they can be
      discovered by `next-api` (see
      https://github.com/vercel/next.js/pull/94922).
      0d1dc023
    • Sam Poder's avatar
      [turbopack] Use experimental chunking heuristics (#95026) · 5c7a4468
      Sam Poder authored
      <!-- NEXT_JS_LLM_PR -->
      5c7a4468
    • Sam Poder's avatar
      [turbopack] Set `chunking_heuristics` on each `ChunkGroupInfo` (#95021) · be6039d7
      Sam Poder authored
      This PR changes `compute_chunk_group_info` so that chunks inherit
      heuristics from the entry chunk groups that reference them. For
      entry-points, if a chunk group is referenced by any entry point, it
      inherits a true value. For clusters, chunk groups inherit all the
      clusters that the groups that reference them are a part of.
      be6039d7
    • Sam Poder's avatar
      [turbopack] Thread `chunkingHeuristics` through to chunk groups (#95020) · ab8e8329
      Sam Poder authored
      This takes `chunkingHeuristics` from `next.config.js` and puts it on
      `ChunkGroupEntry` so it can be on `ChunkGroupInfo` which will then make
      it available in `make_production_chunks`
      ab8e8329
    • Sam Poder's avatar
      [turbopack] Add an experimental `chunkingHeuristics` to `next.config.js` (#95019) · 99aba86a
      Sam Poder authored
      This PR adds new experimental options to `next.config.js`, they are: the
      request cost, “clusters” of routes where should chunk more (because the
      Z+Z case in `make_production_chunks` is more likely), “entry points”
      where we prioritize larger merged chunks for fast initial page loads
      (achieved by increasing P(N=1)), and a bounce rate to configure P(N=1)
      and P(N=2) based on site data.
      99aba86a
    • Janka Uryga's avatar
      test: fork select tests on partialPrefetching (#95279) · 3767dfae
      Janka Uryga authored
      Stopgap until we make this a proper part of the CI matrix
      3767dfae
    • Sukka's avatar
      Enhance ESLint rule `no-location-assign-relative-destination` (#93057) · e37c6d63
      Sukka authored
      - Implements `location` scope check (suggested by @bgw in
      https://github.com/vercel/next.js/pull/92900#discussion_r3107167621),
      ensuring `location` is a true global variable before reporting.
      - Implements basic variable tracking (suggested by @icyJoseph in
      https://github.com/vercel/next.js/pull/93057#issuecomment-4281583840)
      
      ---------
      Co-authored-by: 's avatarBenjamin Woodruff <benjamin.woodruff@vercel.com>
      e37c6d63
    • Will Binns-Smith's avatar
      Add docs for `experimental.turbopackRustReactCompiler` (#95280) · 1fee8041
      Will Binns-Smith authored
      This adds documentation for this config flag.
      
      Test Plan: Tested each hyperlink within the repo.
      
      ---------
      Co-authored-by: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
      1fee8041
    • Andrew Clark's avatar
      Fix: Update the URL when a client navigation redirects to a rewritten route (#95207) · ae6d43b8
      Andrew Clark authored
      On a client-side navigation, when a proxy/middleware redirected the
      requested URL to a destination that was itself rewritten to a
      dynamically rendered route, the page content updated correctly but the
      address bar stayed on the original URL. Hard navigations (reload, typing
      the URL) were unaffected.
      
      This happened because the navigation optimistically committed the
      predicted URL up front, and when the redirect resolved to a route with
      the same shape as the prediction, the router treated the navigation as
      already correct and never reconciled the address bar.
      
      A redirect discovered during a navigation now invalidates the prediction
      and re-resolves the route, so the address bar reflects the redirect
      destination.
      
      Adds an end-to-end test covering the regression.
      
      Fixes #95195
      ae6d43b8
    • Tobias Koppers's avatar
      Turbopack: replace cssChunking graph `moduleFactorCost` with `weightDistribution` (#95088) · 1682685a
      Tobias Koppers authored
      ## Summary
      
      Reworks the cost model of the experimental graph CSS chunking algorithm
      (`experimental.cssChunking: 'graph'`, Turbopack only) and retunes its
      defaults.
      
      - **Replaces the `moduleFactorCost` option with `weightDistribution`.**
      The old `moduleFactorCost` term penalized a chunk purely by `chunk_size
      / group_total_size`, which charged a chunk group even for CSS it fully
      needs and never actually measured overshipping.
      - **New per-group cost** is `chunk_group_weight * (chunk_size +
      request_cost)`, summed over the chunk groups that load a chunk, where
      `chunk_group_weight = group_total_size ^ (-weightDistribution)` is
      precomputed once per group. `weightDistribution = 0` weights every chunk
      group equally; higher values give smaller chunk groups a larger weight,
      so the algorithm overships less to small pages at the cost of more
      requests. The size weighting subsumes the explicit overship penalty, so
      the metric stays chunk-local and the greedy merger is unchanged.
      - **Retunes defaults:** `requestCost` `20000` → `100000` (bytes) and
      `weightDistribution` default `0.1`.
      
      Config shape (object form): `{ type: 'graph', requestCost?,
      weightDistribution? }`. The change is wired end to end through the
      config schema/types, `StyleGroupsAlgorithm::Graph`, and the chunking
      algorithm.
      
      ## Verification
      
      - `cargo test -p turbopack-core --lib style_groups_graph` (54 passed,
      incl. a new test asserting `weightDistribution` keeps an unneeded module
      out of a small group's chunk)
      - `pnpm test-start-turbo test/e2e/app-dir/css-order/css-order.test.ts`
      (243 passed, 12 todo) — confirms chunk shapes/request counts at the new
      defaults across the `graph` and `graph-object` modes
      
      <!-- NEXT_JS_LLM_PR -->
      1682685a
    • Vercel Release Bot's avatar
    • Aurora Scharff's avatar
      skills(cc-adoption): tighten requires, sequencing, terminology (#95225) · aab6bf70
      Aurora Scharff authored
      ### What?
      
      Tightens `skills/next-cache-components-adoption/SKILL.md` based on four
      agent friction logs.
      
      ### Why?
      
      - Non-interactive strategy default was ambiguous on small apps.
      - `experimental.dynamicIO` is fatal at config-schema time, not
      segment-config time — needs its own bullet.
      - The `cache-components-instant-false` codemod doesn't translate
      `revalidate`/`dynamic`/`fetchCache`; agents expected an immediate
      passing build and got a failed one.
      - "Build passes immediately" overpromised — only true once sync-IO +
      segment configs are translated.
      - "Green" → "passing" for clarity.
      
      ### How?
      
      13 insertions / 7 deletions, single file. New `dynamicIO` bullet,
      restructured pre-codemod work into a numbered list (sync-IO + segment
      configs), softened the Incremental headline, simplified the
      non-interactive default. No docs material duplicated — recipes stay in
      the [migration
      guide](https://nextjs.org/docs/app/guides/migrating-to-cache-components).
      
      <!-- NEXT_JS_LLM_PR -->
      aab6bf70
    • Sebastian "Sebbie" Silbermann's avatar
      Avoid bundling client-nodemodules used by `unstable_rethrow` in client-browser modules (#95196) · 85f92319
      Sebastian "Sebbie" Silbermann authored
      There are more client-node modules being bundled into `client-browser`
      which I'll fix in a followup (with codegen).
      
      Our internal `unstable-rethrow` will now have a version without suffix
      (unbundled or client-node) and a client-browser only version
      (`.browser`) that bundlers alias to for client-browser which will always
      be bundled.
      
      For the specific modules being removed from client-browser, check the
      second commit with the actual change. The first commit fixes the
      `browser-chunk` test to include `next/src/server` in a snapshot.
      
      Closes #95189
      85f92319
    • Tariqul Islam Tuhin's avatar
      fix(turbopack): dedupe filename/exportedName in server-reference-manifest worker entries (#95242) · f23a96f0
      Tariqul Islam Tuhin authored
      ### What
      
      Turbopack's `server-reference-manifest` emitter stores `filename` and
      `exportedName` **twice**: once hoisted to the action-entry level
      (correct), **and** redundantly inside *every* per-page
      `ActionManifestWorkerEntry`. This PR removes the per-worker copies so
      the worker map only carries `{ moduleId, async }` — matching the webpack
      backend, which already emits them at the entry level only.
      
      The emitter even comments the intent (`// Hoist the filename and
      exported_name to the entry level`) and does the hoist — the per-worker
      fields are vestigial.
      
      ```rust
      // crates/next-api/src/server_actions.rs
      entry.workers.insert(&key, ActionManifestWorkerEntry {
          module_id: loader_id.clone(),
          is_async: …,
          exported_name,                 // ← removed (already on entry)
          filename: filename.as_ref(),   // ← removed (already on entry)
      });
      entry.exported_name = exported_name;   // hoist (kept)
      entry.filename = filename.as_ref();    // hoist (kept)
      ```
      
      ### Why it matters
      
      `filename` and `exportedName` are invariant per action, but the worker
      map has **one entry per page that can reach the action**, so these
      strings get repeated `O(actions × pages)` times. On a large App Router
      app (`output: 'standalone'`, `cacheComponents: true`) this is the
      dominant cost of the manifest:
      
      - ~1,650 routes, **1,847 references → 589,349 `workers` entries**
      - `server-reference-manifest.json` = **170 MB** / `.js` = **182 MB**
      (plus the duplicate copy under `.next/standalone`, plus ~314 MB of
      per-route manifests)
      - A single `'use cache'`/action reachable from a shared client is
      registered on **1,638 pages**, each repeating the full `filename` string
      
      Dropping the two redundant per-worker fields removes the largest
      repeated strings from every worker entry, shrinking the manifest
      substantially with no information loss.
      
      ### Why it's safe (consumer-compatible)
      
      - The webpack backend already emits worker entries as `{ moduleId, async
      }` only, with `filename`/`exportedName` at the entry level — so this
      aligns Turbopack with webpack, not introduces a new shape.
      - The only first-party reader,
      `packages/next/src/server/mcp/tools/get-server-action-by-id.ts`, reads
      `entry.filename` / `entry.exportedName` (entry level) and types
      `workers` as `Record<string, any>` — it never reads the per-worker
      copies.
      
      ### Changes
      
      - `crates/next-core/src/next_manifests/mod.rs` — drop `exported_name` +
      `filename` from `ActionManifestWorkerEntry` (keep `module_id`,
      `is_async`).
      - `crates/next-api/src/server_actions.rs` — stop assigning them in the
      worker insert (entry-level hoist unchanged).
      
      ### Notes
      
      - Verified by reading the emitter, the manifest types, and the consumer;
      I don't have a local Turbopack build, so CI is the source of truth here
      — if any manifest **snapshot fixtures** include per-worker
      `filename`/`exportedName`, they'll need regenerating.
      - Context / measurements: vercel/next.js#95241.
      f23a96f0
    • Sebastian "Sebbie" Silbermann's avatar
    • Joseph's avatar
      fix: preserve repeated search params in client page segment cache keys (#94863) · c3bf2a39
      Joseph authored
      Fixes: #94821, #92787, #93104
      
      Using `Object.fromEntries` on URLSearchParams, drops repeated keys.
      
      ```js
      const s = '?foo=bar&foo=baz'
      Object.fromEntries(new URLSearchParams(s)) // { foo: 'baz' }
      ```
      
      There's already a function, `urlSearchParamsToParsedUrlQuery`, which
      handles this case.
      
      
      https://github.com/vercel/next.js/blob/40296fe53f40ffe6a0e2184879bd5e294d271ce4/packages/next/src/client/route-params.ts#L235
      
      ```js
      urlSearchParamsToParsedUrlQuery(new URLSearchParams(s)) // { foo: ['bar', 'baz'] }
      ```
      
      - [x] The e2e off one of the issue reports, I'll try to simplify it.
      c3bf2a39
    • Niklas Mischkulnig's avatar
      Improve typing of `decodeReply` (#95263) · 8a027d78
      Niklas Mischkulnig authored
      The types were unnecessarily specific (it doesn't always return a `T[]`)
      8a027d78
  2. 28 Jun, 2026 2 commits
  3. 26 Jun, 2026 15 commits
    • next-js-bot[bot]'s avatar
      v16.3.0-canary.69 · 4b164d76
      next-js-bot[bot] authored
      4b164d76
    • Luke Sandberg's avatar
      [turbopack] Support undoable modifications for many field types on TaskStorage (#95180) · 0e8d6b30
      Luke Sandberg authored
      ## What
      Allow some modifications that turn out to be no-ops to be undone on
      TaskStorage. This saves us some redundant check-then-mutate cycles.
      
      This doesn't apply to every field type
      * `Option<T>` - still read-check-modify
      * `CounterMap<T>` - updates are unconditional tracks and removals use
      the undo approach
      * `AutoSet`/`AutoMap` - mostly uses the new 'undo' approach 
      * `take` as a bulk operation does not, taking an empty set is rare and
      cheap to check for
      * `AutoMap::insert` doesn't use the undo approach or even check, we
      always track a modification since all callers are only inserting unique
      values anyway
      
      A few other incidental cleanups were landed as well.
      
      ## Why
      
      Avoid redundant hash lookups.
      
      ## How
      
      Have `track_modification` return a new TrackOutcome that records what
      modifications were made and then in the undo case we can pass it to a
      new `undo_track_modification` function which can reverse it. This is a
      little brittle since both operations need to occur within a single lock
      transition
      
      I considered using a 'lambda' oriented approach but decided against it
      since it would be awkward for some of the mutators and as all the
      callers are generated by a macro (well _almost_ all callers) it isn't
      too risky.
      0e8d6b30
    • Luke Sandberg's avatar
      Record size metrics to our compaction and persistence spans (#94977) · 91b3570e
      Luke Sandberg authored
      Add data about persistence and compaction size to our spans
      
      This will show up in trace data collected by `NEXT_TURBOPACK_TRACING`
      and in the default trace spans collected by next.js
      91b3570e
    • Luke Sandberg's avatar
      Don't track modifications to transient data stored in tasks (#95133) · 6dc3a5a7
      Luke Sandberg authored
      Many fields in TaskStorage store a mix of transient and persistent data.
      When we serialize we leverage the `filter_transient` tag (and the
      `IsTransient` trait) to avoid persisting it, however, when mutations
      occur we are still marking the tasks as `modified` even when we are only
      modifying transient data.
      
      This leads to unnecessary persistence cycles.
      
      The solution is simply to not call `track_modification` when the
      modification is about transient data items.
      
      For most fields this is handled in the macro accessors, but for
      `cell_data` this is managed via some new 'handwritten' mutators
      implemented on `TaskGuard`. This is desirable to decrease the number of
      times we do registry lookups since most callers who modify the cell_data
      already have the ValueType in hand
      6dc3a5a7
    • Tim Neutkens's avatar
      fix: preserve middleware rewrite query in Pages API routes (#94905) · 668cd3a4
      Tim Neutkens authored
      ### What?
      
      - Preserve the resolved routing `query` and dynamic `params` when
      `NextNodeServer.runApi` invokes a bundled Pages API route.
      - Keep `req.url` restored to the original browser-visible request URL
      for compatibility.
      - Add an end-to-end regression test for a middleware rewrite from
      `/foo/bar?key=value` to `/api/proxy/bar?added=1&extra=2` using an
      optional catch-all Pages API route.
      
      ### Why?
      
      Middleware routing correctly resolves the destination query and
      catch-all parameters, but the Node Pages API path restores `req.url`
      before invoking the bundled handler and previously forwarded only
      `waitUntil`. The handler then reparsed the original URL and produced
      only `{ key: "value" }`, dropping the rewrite-added `added` and `extra`
      values and the destination `slug` parameter.
      
      This restores the behavior from Next.js 14 that regressed during the
      Pages API handler-interface migration. The issue affects both webpack
      and Turbopack because the data is lost in shared server routing after
      bundling.
      
      The public documentation describes the pieces separately—rewrites
      preserve the original URL, dynamic API parameters appear in `req.query`,
      and resolved routing queries include middleware changes—so this is a bug
      fix rather than a new API contract.
      
      Fixes #94647
      
      ### How?
      
      `runApi` now forwards the existing request metadata together with the
      resolved `query` and `match.params` through the bundled handler context.
      The Pages API entrypoint already installs supplied request metadata
      before `routeModule.prepare()`, which then uses these routed values
      while retaining the original `req.url`.
      
      The regression test asserts that:
      
      - `req.url` remains `/foo/bar?key=value`.
      - `req.query` contains the original `key`, rewrite-added `added` and
      `extra`, and catch-all `slug` values.
      
      ### Verification
      
      - `pnpm --filter=next build`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-dev-turbo
      test/e2e/middleware-rewrites/test/index.test.ts -t "should preserve
      rewrite query and dynamic params in Pages API routes"`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-dev-webpack
      test/e2e/middleware-rewrites/test/index.test.ts -t "should preserve
      rewrite query and dynamic params in Pages API routes"`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-start-turbo
      test/e2e/middleware-rewrites/test/index.test.ts -t "should preserve
      rewrite query and dynamic params in Pages API routes"`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-start-webpack
      test/e2e/middleware-rewrites/test/index.test.ts -t "should preserve
      rewrite query and dynamic params in Pages API routes"`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-dev-turbo
      test/e2e/api-support/api-support.test.ts -t "query|dynamic"`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-start-webpack
      test/e2e/api-support/api-support.test.ts -t "query|dynamic"`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-dev-turbo
      test/e2e/custom-routes/custom-routes.test.ts -t "api rewrite"`
      - `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-start-webpack
      test/e2e/custom-routes/custom-routes.test.ts -t "api rewrite"`
      - Pre-commit lint-staged checks (Prettier and ESLint)
      - Not run continuously: `pnpm --filter=next dev` (the local watcher hits
      the environment open-file limit with `EMFILE`; the focused package build
      passed)
      
      <!-- NEXT_JS_LLM_PR -->
      
      <!-- CURSOR_SUMMARY -->
      ---
      
      > [!NOTE]
      > **Medium Risk**
      > Changes shared Pages API request routing in the Node server and
      adapter i18n route generation; behavior is restored to pre-regression
      semantics but affects all bundled Pages API invocations.
      > 
      > **Overview**
      > Fixes a regression where **Pages API** handlers saw only the original
      URL query after a middleware rewrite, because `runApi` restored
      `req.url` but did not pass the router’s resolved `query` and `params`
      into the bundled handler context.
      > 
      > `NextNodeServer.runApi` now supplies `requestMeta` (including merged
      `query` and `match.params`) alongside `waitUntil`, so `req.query` keeps
      rewrite-added parameters and catch-all segments while `req.url` stays
      the browser-visible path.
      > 
      > Adapter build output no longer applies i18n locale prefixing to
      dynamic **Pages API** routes (`shouldLocalize` excludes API pages);
      regular pages still get `nextLocale` routing.
      > 
      > Regression coverage: middleware rewrite e2e (`/foo/bar` → catch-all
      API) and a production adapter test with `i18n` enabled.
      > 
      > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
      ad415cfe574f67dd7385662a01c2c9f3c89af521. Bugbot is set up for automated
      code reviews on this repo. Configure
      [here](https://www.cursor.com/dashboard/bugbot).</sup>
      <!-- /CURSOR_SUMMARY -->
      668cd3a4
    • Jiwon Choi's avatar
      Return APP_PAGE instead of PAGES for production Instant Navigation tests (#95184) · b1f49163
      Jiwon Choi authored
      ### Why?
      
      Current behavior:
      https://github.com/vercel/next.js/actions/runs/28225010081/job/83615571987?pr=95184#step:31:8732
      
      For a minimal-mode resume request carrying the Instant Navigation
      testing cookie, Next.js skips the postponed render so the test receives
      only the prefetched static shell. The resulting empty continuation was
      represented as `PAGES`, but the App Page handler requires `APP_PAGE`,
      causing error:
      
      ```
      Error: Invariant app-page handler received invalid cache entry PAGES
      ```
      
      ### How?
      
      Return an empty `APP_PAGE` response with the correct HTML or RSC content
      type and postponed metadata. If the document continuation has no
      `<head>` chunk, insert the Instant Navigation bootstrap while flushing
      the stream.
      
      Add production regression coverage for document and RSC-prefetch resume
      requests using build-generated postponed state.
      
      <!-- NEXT_JS_LLM_PR -->
      b1f49163
    • Sebastian "Sebbie" Silbermann's avatar
      [ci] skip Datadog git metadata upload on junit upload (#95210) · 287c04cf
      Sebastian "Sebbie" Silbermann authored
      Pass `--skip-git-metadata-upload` to all `datadog-ci junit upload`
      invocations. This stops the in-CI git metadata sync, which forces an
      expensive `git fetch` unshallow on every shallow CI checkout before each
      test-report upload.
      
      We don't need to upload git metadata manually since our GH actions are
      directly integrated with DataDog via app.
      
      > Git metadata upload is only required if you can’t integrate your CI
      provider directly with Datadog. If you are using a [source code provider
      integration](https://docs.datadoghq.com/code_coverage/setup/?tab=github#integrate-with-source-code-provider),
      such as Datadog GitHub app or Gitlab integration, you can disable the
      git metadata upload by passing the --skip-git-metadata-upload=1 flag to
      the datadog-ci coverage upload command, like this:
      
      
      --https://docs.datadoghq.com/code_coverage/setup/?tab=github#coverage-upload-outputs-could-not-sync-git-metadata-error
      
      ## test plan
      
      - [x] no more unshallow when uploading junit reports to DataDog: [upload
      from this branch shows no "syncing git
      metadata"](https://github.com/vercel/next.js/actions/runs/28252881331/job/83708778650?pr=95210#step:38:113)
      that [you'd used to see on prior
      uploads](https://github.com/vercel/next.js/actions/runs/28252765955/job/83708485242?pr=95207#step:38:112)
      287c04cf
    • Jude Gao's avatar
      next-dev-loop: require agent-browser >= 0.31.1 (#95209) · d6952ba6
      Jude Gao authored
      ## Summary
      
      Bump the `agent-browser` floor in the `next-dev-loop` skill from `>=
      0.31.0` to `>= 0.31.1`.
      
      One-line change to the `requires` section; the listed capabilities
      (React introspection, worktree-scoped `session id`, idempotent
      `--restore`, launch-flag reconciliation) are unchanged.
      
      ## Verification
      
      - `prettier --check skills/next-dev-loop/SKILL.md` → clean.
      
      <!-- NEXT_JS_LLM_PR -->
      d6952ba6
    • Luke Sandberg's avatar
      Bump Rust toolchain (#95205) · b2add075
      Luke Sandberg authored
      Bump rust nightly version
      
      Critically this fixes a bug in Rust Analyzer where it didn't understand
      'pattern_types' a new rust feature that is used by `NonZero<T>` types
      for example)
      
      
      ![image.png](https://app.graphite.com/user-attachments/assets/04c3a119-d08b-457a-bd55-6fe94da24806.png)
      
      So now we can get feedback on the size of types containing vc!
      
      From scanning release notes there is nothing major that i can see.
      Clippy did flag one new warning that is being addressed as well.
      b2add075
    • Aurora Scharff's avatar
      docs(errors): reorder blocking-prerender-dynamic fixes to Stream, Cache, Block (#95198) · 6c22d02c
      Aurora Scharff authored
      The runtime error message for `blocking-prerender-dynamic` lists fixes
      in the order **[stream] → [cache] → [block]** (see
      `packages/next/src/server/app-render/blocking-route-messages.ts`).
      
      Every other surface (dev overlay fix cards, the blog post on
      `nextjs.org/blog/next-16-3-instant-navigations`, the in-post bullets,
      the `## Stream, Cache, or Block` section heading) uses the same order.
      Only this docs page was out of sync, listing Cache first.
      
      This PR:
      
      - Swaps the order of the `FixOption` cards under `## Ways to fix this`
      to `stream → cache → block`.
      - Swaps the body sections `## Cache the component or data` and `## Wrap
      in or move into Suspense` to match.
      
      No content changes inside either section — pure reorder.
      6c22d02c
    • Hendrik Liebau's avatar
      Hard-navigate to app routes shadowed by a pages dynamic route (#95185) · f81c34f8
      Hendrik Liebau authored
      When an App Router route begins with a dynamic segment (for example
      `app/[locale]/about`), a client-side navigation from a Pages Router page
      could render the wrong route. The Pages Router resolves the destination
      against its own routes only, so `/en/about` would match a less specific
      Pages Router dynamic route such as `pages/[locale]/[category]` instead
      of the App Router page. The server pools app and pages routes and ranks
      them by specificity, so a hard reload always rendered the correct App
      Router page; only the client-side soft navigation diverged.
      
      The client router filter is responsible for detecting destinations owned
      by the other router and forcing a hard navigation, but
      `createClientRouterFilter` only recorded the static prefix of a dynamic
      route. App routes whose first segment is dynamic have no static prefix,
      so they contributed nothing to the filter and the Pages Router never
      learned to hand them off. The filter now also stores a normalized
      pattern for those routes, with dynamic segments replaced by a
      placeholder token (`/[locale]/about` becomes `/[]/about`). After the
      Pages Router resolves a navigation to a dynamic route,
      `hasDynamicFilterCandidate` reconstructs the candidate app-route
      patterns from that route and the concrete path and triggers a hard
      navigation when any candidate is present in the dynamic filter. This
      also covers catch-all and optional catch-all pages routes, whose final
      parameter absorbs a variable number of segments. The shared placeholder
      token and the client-side check live in the new
      `dynamic-filter-pattern.ts`, while the build-only encoder stays in
      `create-client-router-filter.ts`.
      
      The change only ever turns a soft navigation into a hard navigation, and
      only when an app route is genuinely more specific than the resolved
      pages route, so a structural match always agrees with the server's
      resolution. Apps without dynamic app routes are unaffected because the
      dynamic filter stays empty.
      
      The `pages-to-app-routing` end-to-end suite is restructured around a
      `fixtures/` directory and gains coverage for the dynamic-segment
      shadowing, the catch-all and optional catch-all variants, `basePath`,
      middleware, and a guard that legitimate Pages Router dynamic routes
      still navigate client-side. The first request to a not-yet-compiled
      dynamic route can return a transient 404 in development, a pre-existing
      source of CI flakiness, so the tests now warm the route up with a direct
      request before driving the browser.
      
      fixes #74696
      f81c34f8
    • Aurora Scharff's avatar
      [dev overlay]: restructure Copy-as-prompt body into a step-by-step checklist (#95186) · ff3a5f9d
      Aurora Scharff authored
      ## What
      
      Restructures the dev overlay's **Copy as prompt** body from three
      loosely-grouped instructions into a seven-step ordered checklist.
      
      ## Why
      
      Agents tend to do one thing per step. The old step 4 bundled "reload in
      browser," "set up browser tooling," "check the shell," "re-check
      siblings," and a before/after capture into a single paragraph, so most
      of it got skipped.
      
      Two other gotchas got their own steps: the empty-shell case (`<Suspense
      fallback={null}>` around the page body passes the build but renders
      nothing) and the sibling re-check on shared-code changes.
      
      ## How
      
      Same checklist shape as the `next-cache-components-adoption` skill's
      per-route loop, so agents following either workflow apply the same
      sequence. Used for the in-overlay copy button and the prompt mirrored in
      `next dev` / `next build` terminal output.
      ff3a5f9d
    • Aurora Scharff's avatar
      docs(insights): restructure error pages and link to preview docs (#95193) · 5ad38b43
      Aurora Scharff authored
      ### What?
      
      Restructure the 15 Insight error pages
      (`errors/blocking-prerender-*.mdx`, `errors/instant-*.mdx`) so they
      orient the reader before diving into fixes, and point at the preview
      docs for the new 16.3 Instant Navigations guide and APIs.
      
      ### Why?
      
      These pages are the first thing devs see when they click the doc link
      from the dev overlay or the build output for a blocking-route /
      instant-navigation error. Previously they opened straight into the
      technical explanation with no signal that this error is part of the new
      16.3 Instant Navigations feature, and several callouts mixed unrelated
      concerns (debug flags inside a top-of-page "Good to know", duplicated
      "Useful links" footers).
      
      ### How?
      
      - **Intro callout box** added to every page, pointing at the 16.3 launch
      blog post and the migration guide so newcomers have an anchor before
      reading the fix.
      - **`## Verifying the fix` section** added near the bottom, gathering
      the debug tips (empty-shell warning, `--debug-prerender`,
      `--debug-build-paths`) that previously sat in a top-of-page "Good to
      know" callout where they were misplaced.
      - **Removed** duplicated "Useful links" footers (already cross-linked in
      body), removed the misplaced top-of-page debug callout.
      - **Switched all 473 doc links** to
      `https://preview.nextjs.org/docs/...` so they resolve against the
      unpublished 16.3 docs (the live nextjs.org docs don't have the Instant
      Navigations guide or the route-segment-config/instant API reference
      yet).
      
      Split out of #95186 (Copy-as-prompt checklist) which was the same branch
      but a separate feature.
      
      Closes NEXT-
      
      <!-- NEXT_JS_LLM_PR -->
      5ad38b43
    • niketchandivade's avatar
      docs: fix preview message typo (#95050) · 6a5dde61
      niketchandivade authored
      ## What?
      
      Fixes a typo in the preview message.
      
      - This is page is a preview.
      + This page is a preview.
      
      ## Why?
      
      The current text contains a grammatical error that is shown when preview
      mode is enabled.
      
      ## Testing
      
      * Verified the updated text renders correctly.
      * No functional changes.
      6a5dde61
    • Will Binns-Smith's avatar
  4. 25 Jun, 2026 5 commits