- Rework the
`/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache`
API reference.
- Adjust the table notes in
`/docs/app/api-reference/turbopack#configuration` — `[^1]` works well,
but the table notes are auto-magically placed at the bottom of the page.
Going with this hand rolled table notes for now.
- Tidy the Build Caching section in
`/docs/app/api-reference/turbopack#configuration`
- Update the Upgrade to version 16 section on dev/build cache
- Removed the `Build caching` from Webpack gaps
- Added Filesystem caching to Performance and Fast Refresh
Reworks the instant-navigation guide's e2e testing example to cover both
ways a route is reached: a direct visit (SSR document load) and a client
navigation.
Each test wraps the navigation in `instant()` and asserts the shell
renders while the streamed content is held back, then appears after.
Also documents where the testing API is available: automatically under
`next dev`, and in a production build via
`experimental.exposeTestingApiInProductionBuild`.
Closes:
https://linear.app/vercel/issue/DOC-6477/instant-e2e-helper-for-ssr-and-soft-navs-snippets-show-difference
---------
Co-authored-by: Aurora Scharff <aurora.sofie@gmail.com>
Co-authored-by: Aurora Scharff <66901228+aurorascharff@users.noreply.github.com>
## Summary
- clarify how runtime foundations, interactive workflows, and unattended
loops fit into the AI agents and Instant Navigation guides
- harden the Cache Components and Partial Prefetching Skills around
capability checks, trustworthy `instant()` tests, route scope, and
real-app verification failures
- add migration-guide comments to temporary Partial Prefetching route
config and update `remove-partial-prefetch` to remove only generated
comments while preserving runtime-prefetch TODOs and user comments
This keeps the experimental Partial Prefetching optimizer in #96471
separate.
## Testing
- `pnpm --filter @next/codemod build`
- `pnpm --filter @next/codemod test --
transforms/__tests__/remove-partial-prefetch.test.js --runInBand`
## Summary
Enable the project-local TypeScript CLI checker by default during `next
build`, while preserving `experimental.useTypeScriptCli: false` as an
opt-out to the TypeScript compiler API. Update the TypeScript 7
guidance, diagnostics, tests, and documentation to match the new
default.
## Verification
- `pnpm exec jest --runTestsByPath test/unit/isolated/config.test.ts`
- Pre-commit lint-staged checks passed (Prettier and ESLint)
- Not run: `pnpm test-start-turbo
test/production/app-dir/typescript-cli/typescript-cli.test.ts` (isolated
fixture dependency installation was blocked by unavailable npm registry
access)
- Not run: `pnpm --filter=next types` (repository has pre-existing
unrelated TypeScript errors)
<!-- NEXT_JS_LLM -->
## Summary
Enable `experimental.turbopackFileSystemCacheForBuild` by default in all
environments, including generic CI. Explicitly setting the option to
`false` remains the opt-out. Update the focused coverage and
documentation to match.
## Verification
- `IS_TURBOPACK_TEST=1 pnpm test-start-turbo
test/e2e/filesystem-cache/build-cache-default.test.ts`
- `pnpm prettier --with-node-modules --ignore-path .prettierignore
--check packages/next/src/server/config-shared.ts
test/e2e/filesystem-cache/build-cache-default.test.ts
docs/01-app/03-api-reference/08-turbopack.mdx
docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackFileSystemCache.mdx`
- Not run: `pnpm --filter=next build` (the checkout has 11 pre-existing
TypeScript errors in unrelated files)
<!-- NEXT_JS_LLM -->
### What?
Makes `experimental.turbopackFileSystemCacheForBuild` (Turbopack's
on-disk
filesystem cache for `next build`) enabled by default, matching the
dev-mode
flag. It stays disabled by default in non-Vercel CI environments, and
can
always be turned off explicitly with
`experimental.turbopackFileSystemCacheForBuild: false`.
### Why?
The build filesystem cache greatly speeds up warm builds, but was
previously
opt-in (only auto-enabled for canary builds on the Vercel builder).
Defaulting
it on gives everyone faster subsequent builds, while keeping it off in
non-Vercel CI where the cache is unlikely to persist between builds.
### How?
- `turbopackFileSystemCacheForBuildDefault()` now returns `true` except
when
`isCI && !NOW_BUILDER` (removed the `isStableBuild()` gate).
- The explicit `false` opt-out already works via the existing
`config.experimental?.turbopackFileSystemCacheForBuild || false` read.
- Adds an e2e test (`test/e2e/app-dir/turbopack-fs-cache-build-default`)
asserting `.next/cache/turbopack` is written by default, empty when the
flag
is `false`, and empty in non-Vercel CI.
- Updates the `turbopackFileSystemCache` / Turbopack docs.
<!-- NEXT_JS_LLM -->
---------
Co-authored-by: vercel-fleet[bot] <308483924+vercel-fleet[bot]@users.noreply.github.com>
Co-authored-by: Tobias Koppers <1365881+sokra@users.noreply.github.com>
## Summary
DOM-capable crawlers can consume streamed metadata, but with
cacheComponents enabled, it treated them like HTML-limited bots and
forced a full dynamic render. This meant capable crawlers could not use
the prerendered shell even when they were not matched by
`htmlLimitedBots`.
This change lets DOM-capable crawlers follow the normal PPR shell and
streaming-metadata path. `htmlLimitedBots` remains the source of truth
for requests that need blocking metadata, including when a custom
pattern explicitly matches a DOM-capable crawler.
## Test Plan
Tests were added that contained a Suspense boundary that intentionally
never resolves. The test reads the response stream until it receives the
fallback, then verifies that blocking metadata has already been emitted
while the unresolved page content has not. A fully buffered response
would never return, so this avoids relying on timing or arbitrary
delays.
This PR is stacked on #96366.
Updates the Progressive Web Apps guide’s Offline Support section to
point the primary Serwist + Next.js example at
[`next-turbo-basic`](https://github.com/serwist/serwist/tree/main/examples/next-turbo-basic)
(Turbopack), and keeps a note linking the webpack-based
[`next-basic`](https://github.com/serwist/serwist/tree/main/examples/next-basic)
example.
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
We encourage you to use AI to assist you in researching, creating, and
reviewing changes. However, you must review and deeply understand the
contributions you are making. For this reason, **pull request
descriptions from external contributors must be written by a human**.
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Signed commits
- This repository requires verified commit signatures on protected
branches.
- If this pull request is blocked for unsigned commits, re-sign the
commits and force-push the branch.
- A `Signed-off-by` line in the commit message is not enough.
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
Updates the Progressive Web Apps guide’s Offline Support section to
point the primary Serwist + Next.js example at `next-turbo-basic`
(Turbopack), and keeps a note linking the webpack-based `next-basic`
example.
### Why?
Turbopack is the default bundler, so the main docs link should match
that setup. Webpack users still need a clear path to the older example
without treating webpack as the default.
### How?
In `docs/01-app/02-guides/progressive-web-apps.mdx`, changed the Serwist
docs link from `examples/next-basic` to `examples/next-turbo-basic`, and
rewrote the note to link `examples/next-basic` for webpack.
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: Joseph <sephxd1234@gmail.com>
## What
Updates the Next.js 16 upgrade guide's AI-agent section to present:
- a recommended agent-assisted upgrade path
- a dedicated docs setup section using `npx @next/codemod@canary
agents-md`
- a copy prompt that points to the guide's own docs setup and codemod
sections, uses the Version 16 guide as the source of truth, asks the
agent to communicate tradeoffs, verify with the AI-agent runtime flow
such as `next-dev-loop` when available, and repeat the post-upgrade docs
check
- a non-agent path that keeps the existing upgrade codemod instructions
It also removes the stale external MCP setup from the upgrade flow,
calls out the async Request APIs codemod gap, and clarifies how to
migrate or remove removed `experimental.dynamicIO` /
`experimental.useCache` config.
## Why
The upgrade guide should make the docs setup useful for humans and
agents before migration starts, while keeping the agent prompt concise,
self-contained, and grounded in the docs as the source of truth.
## Checks
- `git diff --check`
- MDX fence balance check
- commit hook: `lint-staged` ran Prettier and ESLint on the changed MDX
file
## Summary
- update the Partial Prefetching adoption skill for the current runtime
prefetching model
- scope the Cache Components optimizer's runtime-prefetch limitation to
URL data
- preserve the optimizer pattern structure for URL data that cannot
move, with Partial Prefetching, targeted `<Link prefetch={true}>`, and
cached URL-data content as the requirements
- make the optimizer follow-up conditional: use targeted
`prefetch={true}` when the app already adopted Partial Prefetching,
otherwise recommend the PPF adoption skill for the broader shared App
Shell model
## Why
Andrew's Partial Prefetching work removes the old `allow-runtime`
route-config model. The skills should teach the current shape: Partial
Prefetching gives links a shared App Shell baseline with lower
duplicated prefetch cost, while `<Link prefetch={true}>` is reserved for
links where resolving URL-specific content before click is worth the
extra server work.
## Validation
- `git diff --check HEAD~1..HEAD`
- grep confirmed no `allow-runtime` / `force-runtime` references remain
in the changed Skill files
- attempted `skill-creator` quick validation, but the local Python env
is missing `yaml`
## Summary
Client-handled Server Action redirects currently return a `303` without
a `Location` header and may include a streamed RSC response body. Some
HTTP intermediaries reject this response or strip its body because it
looks like an HTTP redirect.
Return `200` for client-handled Server Action redirects while continuing
to use `x-action-redirect` and the RSC response. Progressive-enhancement
form submissions still return a standards-compliant `303` with
`Location`.
Fixes#92882Fixes#74026
## Verification
- `HEADLESS=true pnpm test-dev-turbo
test/e2e/app-dir/actions/app-action.test.ts
test/e2e/app-dir/app-basepath/index.test.ts
test/e2e/app-dir/actions/app-action-progressive-enhancement.test.ts`
- `HEADLESS=true pnpm test-start-turbo
test/e2e/app-dir/actions/app-action.test.ts
test/e2e/app-dir/app-basepath/index.test.ts
test/e2e/app-dir/actions/app-action-progressive-enhancement.test.ts`
- `pnpm --filter=next types`
<!-- NEXT_JS_LLM -->
### What?
Update the interactive apps guide's prefetching section for unified
runtime prefetching.
### Why?
#96106 removed the `allow-runtime` segment config, and the guide's
section still described the old model after the mechanical rename: it
told readers session data (cookies, headers) needs the link opt-in, when
the App Shell already carries session-gated UI. Only URL data needs
`prefetch={true}`.
### How?
Rework the section around the per-link model: the shell carries static,
cached, and session output, `prefetch={true}` resolves URL data ahead of
the click, and the static prefetch attempt (#96095) makes the server
cost an internal optimization. Includes a technical-writing pass on the
section (full-noun subjects, split splices) and aligns the Next steps
table row.
The `instrumentation-client` Polyfills docs recommended a conditional
dynamic `import().then()` to load a polyfill. That import is
fire-and-forget: Next.js loads this file synchronously and does not
await it before hydration, so the polyfill can install after components
have already run (see #83905).
- In "Execution timing" mention that only synchronous top-level code
completes before hydration. Call out that a conditional `import()` here
is not awaited, and cross-reference `supported-browsers` for
load-on-demand strategies and the built-in baseline.
- In **`supported-browsers.mdx`**, "fix" the `Conditionally loading
polyfills` example to `await import()` instead of a floating `.then()`,
otherwise, a reader needs to put their code within the `.then` chain of
the polyfill load.
Closes:
https://linear.app/vercel/issue/DOC-6506/revisit-polyfills-with-instrumentation-client
Removes the "allow-runtime" prefetch config, and turns its behavior on
implicitly wherever Partial Prefetching is enabled.
The original motivation for "allow-runtime" was to give apps more
control over server costs triggered by prefetches. Until a route
explicitly opts in, prefetches would only be served from the CDN, not
from the server. The problem, though, was it was very confusing to know
when to add or remove this configuration. The incentive for many apps
was to add it everywhere, with no clear signal for when to remove it.
Our updated thinking is that Partial Prefetching itself already provides
sufficient protection against runaway prefetching costs: per-link
prefetches only happen on Link components that explicitly opt in with
the prefetch prop.
The optimizations landed earlier in this stack also make allow-runtime
less necessary: on pages where all the content is statically renderable,
prefetches are served from the static cache and no runtime request is
ever issued; only a page that accesses non-static data is prefetched at
runtime.
The upshot of this decision is that runtime versus static becomes an
internal optimization; the same content gets prefetched regardless of
whether or how Next.js is able to optimize it.
### What?
Restructure the AI agents guide into a step-by-step progression and
close the coverage gaps against the 16.2 and 16.3 AI blog posts.
### Why?
The guide read as a feature list and was missing agent-facing features
the blog posts announced: the actionable error menus with the **Copy
prompt** button and per-error `/docs/messages` pages, the `.md` /
`llms.txt` docs access path, and the `.next/dev/lock` behavior that
keeps agents from stacking dev servers.
### How?
Four steps now sequence the setup (bundled docs, runtime visibility,
errors, skills), with the new content folded in where it belongs. The
skills intro states the knowledge-vs-workflow split (bundled docs are
the source of truth, skills are for workflows). Cross-links the instant
navigation AI workflow and the building guide's `--debug-prerender`
section, and the terminal example uses the current message wording
rather than the blog's pre-stable snapshot. The `#existing-projects`
anchor and per-skill anchors are unchanged for published inbound links;
instant-navigation's link to runtime visibility is updated to the new
heading.
## Summary
Add Vite-compatible `caseSensitive` support to `import.meta.glob()`.
Matching remains case-sensitive by default, while `caseSensitive: false`
applies case-insensitive matching to directory traversal, filenames,
positive patterns, and negative patterns.
The option is included in matcher equality and non-default virtual
module identity, and is exposed through diagnostics, TypeScript
declarations, and the Turbopack options reference.
## Verification
- `cargo test -p turbo-tasks-fs glob`
- `cargo nextest run -p turbopack-tests -E "test(import_meta_glob) and
not test(import_meta_glob_errors)"`
- `cargo fmt --all -- --check`
- `pnpm build-all` and `pnpm --filter=next types` are blocked by
current-canary `sharp.default` type errors in
`packages/next/src/server/image-optimizer.ts`
<!-- NEXT_JS_LLM -->
## 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.
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.
## 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.
### 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.
Building on top of @agadzik work (see first commit)
Adds prerender route metadata to help downstream consumers understand
the nature of build-time prerenders
We break down prerender taxonomy as follows
routeType describes what the prerender serves:
* `route`: a non-UI endpoint, such as a Route Handler.
* `page`: a page whose route parameters are fully known.
* `shell`: a reusable PPR shell for a parameterized page.
* `fallback`: a fallback that may serve or specialize additional
parameter values.
response describes how complete the static response is:
* `complete`: the prerender contains the completed response.
* `initial`: an initial response is available, but the page UI is
incomplete; in practice this applies to partially prerenderable UI
routes.
* `empty`: there is no initial static response to send.
compute describes the request-time work required:
* `static`: no request-time server compute is needed.
* `resuming`: request-time compute resumes from the static response.
* `blocking`: the initial response is blocked until request-time compute
starts, but it may stream while that compute continues.
`htmlSize` reports the byte size of prerendered HTML when the output has
HTML.
The taxonomy is included only on a prerender group’s canonical primary
output—the HTML output for pages or the response output for Route
Handlers—and is omitted from secondary RSC and segment-data outputs.
---------
Co-authored-by: agadzik <andrew.gadzik@vercel.com>
## What
Three things, reviewable per commit:
1. **Point readers at the
[`react-view-transitions`](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-view-transitions)
skill** — same section shape as the partial-prefetching and
cache-components guides.
2. **Fix inaccuracies found by a source audit** (React reconciler, Next
client source, and the guide's own demo repo, which already does most of
these correctly):
- Warn that `default="none"` on a named pair silently kills the morph
unless `share` stays explicit; ship `share="morph" default="none"` in
the customization snippet
- Add `default="none"` to the Suspense fallback VT; align the
reveal-timing prose with its CSS (`--duration-move`)
- Show the gallery-side directional wrapper (one page alone can't
produce the promised slide) and note wrappers go in pages, not layouts
- Correct the untyped-transition examples (back/forward,
`router.refresh()`, reveals — not initial loads) and the `key={slug}`
explanation
- New "Keeping the page interactive" note (`::view-transition {
pointer-events: none }` + named-participant hit-testing caveat);
companion demo PR vercel-labs/react-view-transitions-demo#7
- State the real browser requirement (transition types /
`view-transition-class`, Chromium 125+); note morphs need the
destination rendered in the same commit
3. **Docs side of the `experimental.viewTransition` removal** (#96098 is
the code-only counterpart): config page deleted, setup step replaced
with "works with no configuration."
Prose follows the internal technical-writing guidelines.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Refinements to the Cache Components and Partial Prefetching adoption
skills from running them cold against real apps, plus the doc changes
they lean on.
**Skills**
- PPF: URL-data sweep reworked to feature-by-feature with a resumable
hand-off, and the requires section now says unfinished Cache Components
adoption doesn't gate the skill. Prerender insights are non-blocking dev
signals expected on a fresh branch; only a build-blocking failure stops
the run.
- PPF: install `next-dev-loop` without asking, and verify a real blocker
before falling back.
- CC: dropped the hard-coded `agent-browser` version pin; updated the
PPF cross-reference to the current enable-first flow.
**Docs**
- `runtime-prefetching`: the per-card server cost of `allow-runtime`
grids is specific to `prefetch={true}`, with hover-triggered prefetch as
the mitigation.
- `use-cache`: the request-API restriction follows the call stack
(`next-request-in-use-cache`, can pass build and fail under `next
start`), and the nested-`cacheLife` build error with its fix.
- `instant` route segment config: removed a stale `version: draft` so
the page publishes.
<!-- NEXT_JS_LLM_PR -->
Rewrites `skills/next-cache-components-optimizer` in place: an agentic
loop that encodes the goal as a failing `@next/playwright` `instant()`
e2e, works it to green one route at a time, and ships the test as the
regression guard. Covers initial load (hard navigation) and client-side
navigation (soft navigation) with a test variant each, a VERIFY-RED gate
against tests that fail for the wrong reason, and a setup phase that
records the project's build/deploy/test infrastructure in a
project-local `instant-nav.rig.md`, so the skill assumes no platform.
Keeps the existing skill name, so the path from adoption to optimizer
stays one story and there is nothing new to announce. The previous
dev-loop workflow is replaced wholesale. A PREREQS gate requires Next.js
16+ with `cacheComponents` and a matching `@next/playwright`, and
directs an upgrade first when unmet.
Generalized from a burn-down in the v0 codebase, where this loop ran
agent-driven against CI previews; app-specific examples are scrubbed.
Related: #94152 adds `instant-navs`; happy to converge the two.
Also updates the one paragraph in
`docs/01-app/02-guides/instant-navigation.mdx` that describes this skill
to match the new loop.
---------
Co-authored-by: Aurora Scharff <66901228+aurorascharff@users.noreply.github.com>
Co-authored-by: Aurora Scharff <aurora.sofie@gmail.com>
DOC-6499, two changes:
**Installation: new "Upgrade your Next.js app" section.** The `next
upgrade` command, why frequent updates matter (security patches, fixes,
optimizations, new features), and that upgrading also updates the docs
bundled in the `next` package, with a prompt for agents to catch up
after an upgrade. Links the Upgrading page for version guides.
**AI agents guide expanded.** Beyond bundled docs: runtime visibility
(browser logs forwarded to the terminal, structured error copy, the MCP
server for querying dev-server state) and skills for multi-step
workflows. Covers the 16.2 case where docs are bundled but `AGENTS.md`
is not auto-generated, and cross-links Upgrading.
Claims verified against source (`next-upgrade.ts`, `agentRules`,
`browserDebugInfoInTerminal`, `--no-agents-md`). Docs-only.
The function signature was wrong:
```tsx
function Page({ params } }){
```
Which also prevented prettier from running in the code block. This PR
fixes the signature and formats the code block.
## Summary
The instant / blocking-prerender insight console errors printed a docs
URL under each fix option (two or three anchors per message). This
collapses them to a single `Learn more:` link at the end of each
message, while keeping the `[stream]`/`[cache]`/`[block]` fix-option
labels. It restores the single-link format these builders originally
shipped with.
**Before:**
```
Ways to fix this:
- [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
https://nextjs.org/docs/messages/blocking-prerender-runtime#wrap-in-or-move-into-suspense
- [block] Set `export const instant = false` to allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-runtime#allow-blocking-route
```
**After:**
```
Ways to fix this:
- [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
- [block] Set `export const instant = false` to allow a blocking route
Learn more: https://nextjs.org/docs/messages/blocking-prerender-runtime
```
Covers all 16 insight-kind errors, across `blocking-route-messages.ts`,
`sync-io-messages.ts`, `dynamic-rendering-utils.ts`, and
`instant-messages.ts`.
Because the dev overlay classified these errors by the `#`-anchored docs
URL, `getBlockingRouteErrorDetails` is updated to match the anchor-less
`Learn more:` URL. Console-message snapshots and the guidance-data
extraction test are updated to the new format. The dev-overlay fix-card
data (`instant-guidance-data.ts`) keeps its per-card links, since those
are the overlay UI rather than the console message.
## Verification
- `pnpm --filter=next types`
- Snapshots regenerated with `jest -u` for the affected suites
<!-- NEXT_JS_LLM -->
**What**: Included the examples of static export tools seen in the
[Getting Started guide on deploying with static
exports](https://nextjs.org/docs/app/getting-started/deploying#static-export).
Added a reference to the official Next.js GitHub Pages template.
**Why**: Per discussion #95756, the GitHub Pages template provided by
Next.js can be somewhat easily missed. Its addition to a second location
can alleviate this issue.
**How**: A part of the language used in the Static Exports section of
the Getting Started article was already present in the Static Exports
guide. Therefore, the least obtrusive way to add the reference to the
GitHub Pages template was to include it in said language.
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
We encourage you to use AI to assist you in researching, creating, and
reviewing changes. However, you must review and deeply understand the
contributions you are making. For this reason, **pull request
descriptions from external contributors must be written by a human**.
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Signed commits
- This repository requires verified commit signatures on protected
branches.
- If this pull request is blocked for unsigned commits, re-sign the
commits and force-push the branch.
- A `Signed-off-by` line in the commit message is not enough.
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: Joseph <sephxd1234@gmail.com>
### What?
Adds a "Good to know" to the Interactive apps guide explaining that the
`data-pending` + `group-has-data-pending:`/`has-data-pending:` pattern
compiles to the CSS `:has()` selector, and when to reach for client
state instead.
### Why?
`:has()` is re-evaluated over the anchored subtree whenever the
attribute toggles, so a broad anchor (like the whole board) combined
with a high-frequency interaction can add up. The guide taught the
pattern without noting that scaling limit, so a reader could copy the
board-wide dim into a per-frame interaction and hit style-recalc cost.
### How?
Documentation only. One callout in Step 3, calibrated so the guide's own
board usage stays fine (it toggles only per filter, and dragging
deliberately skips it), and pointing to client state for the
high-frequency case.
### What?
- Adds one clarifying sentence (plus a link) to the "Organize routes
without affecting the URL path" section in
docs/01-app/01-getting-started/02-project-structure.mdx. No behavior
change, docs text only.
---
### Why?
- The existing sentence says you can add a layout.js inside a route
group folder to give it a different layout, but it doesn't say whether
that layout.js nests inside the top-level app/layout.js or replaces it.
Read in order, a reader hits this line before the page ever mentions
removing the top-level layout, so it's genuinely ambiguous at that point
in the page. The nesting behavior is only clarified later, in the
"Creating multiple root layouts" section — and even then, it's explained
for a different, more specific case (removing the top-level layout
entirely to give each route group its own root layout).
---
### How?
- Added one sentence stating that this layout.js nests inside the
top-level app/layout.js like any other layout by default, and linked to
"Creating multiple root layouts" for readers who want the root-layout
behavior instead.
---------
Co-authored-by: Joseph <sephxd1234@gmail.com>
This has been causing a lot of confusion when contributors have been
debugging tree shaking, eg.
https://github.com/vercel/next.js/issues/95698 and the linked issues.
Turbopack's standard tree-shaking features are controlled through the
`turbopackRemoveUnusedExports` and `turbopackRemoveUnusedImports`
options which default to true.
## Summary
<img width="1304" height="1546" alt="CleanShot 2026-07-19 at 01 07
57@2x"
src="https://github.com/user-attachments/assets/b9a6a7c9-dc95-42d5-9cce-f29e6d869d92"
/>
Adds a "Set up your editor" section to the App Router installation
guide. The App Router names files by convention (`page.tsx`,
`layout.tsx`, `route.ts`), so an editor quickly fills with same-named
tabs. This section shows how to tell them apart with VS Code / Cursor
custom editor labels, labeled two folders deep so dynamic routes like
`blog/[id]/page.tsx` do not all collapse to the same `[id]` label. It
includes:
- A copy-paste `.vscode/settings.json` config
(`workbench.editor.customLabels.patterns`) for setting it up by hand.
- A copyable prompt that points a coding agent back at this section to
apply the config, including adapting it to other editors.
- A good-to-know that JetBrains IDEs (WebStorm, IntelliJ) do this
automatically.
## Verification
- Previewed locally against the docs site: the section renders (HTTP
200), with the config block, the prompt card, and the good-to-know all
rendering correctly.
<!-- NEXT_JS_LLM_PR -->
### What?
Remove outdated experimental status notices for `@next/routing` from the
adapters documentation and package README.
### Why?
`@next/routing` is no longer experimental, and the existing notices
incorrectly tie its stabilization to the adapters API.
### How?
Delete the obsolete notices while leaving the routing API documentation
unchanged.
### Verification
- `pnpm prettier --with-node-modules --ignore-path .prettierignore
--write
docs/01-app/03-api-reference/07-adapters/05-routing-with-next-routing.mdx
packages/next-routing/README.md`
- Repository lint-staged checks passed during commit
- Not run: runtime tests (documentation-only change)
<!-- NEXT_JS_LLM_PR -->
## What
Follow-up to #95365. Documents adopting Partial Prefetching end to end:
- Restructures the [Adopting Partial Prefetching
guide](https://github.com/vercel/next.js/blob/canary/docs/01-app/02-guides/adopting-partial-prefetching.mdx)
around the two paths: enable `partialPrefetching` and audit every `<Link
prefetch={true}>` against a per-case decision table, or adopt
incrementally per route with the
[`instant-link-prefetch-partial`](https://nextjs.org/docs/messages/instant-link-prefetch-partial)
insight as the worklist. Adds `Auditing routes for URL data` and
`Prefetching URL data` sections.
- Adds the `remove-partial-prefetch` codemod, which strips the redundant
per-route `prefetch = 'partial'` exports once the flag is on while
preserving comments and other `prefetch` values.
- Adds the `next-partial-prefetching-adoption` skill that sequences the
guide for agents: audit, enable + codemod, URL-data sweep, verify,
optional runtime prefetching.
- Aligns the `instant-link-prefetch-partial` error page, `<Link>`
reference, glossary, and Interactive apps guide with the same prefetch
model.
## Why
With the flag on, `<Link prefetch={true}>` no longer delivers dynamic
content, and shell validation flags `params`/`searchParams` reads
outside `<Suspense>`. Adopters need one guide that sequences the audit,
the flag, and both insights, and an agent skill that follows it.
Stacked on #95365 (base: `codex/instant-shell-link-data`) since it links
to the `instant-shell-url-data` error page that PR introduces. GitHub
will retarget to `canary` when that merges.
<!-- NEXT_JS_LLM_PR -->
Joseph