docs(cache-components): clarify allow-runtime, sync-IO and instant=false, CLS fallback#94997
Merged
Conversation
Contributor
Tests PassedCommit: cac8d42 |
Contributor
Stats cancelledCommit: cac8d42 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Next.js documentation to more accurately describe Cache Components / Partial Prefetching behavior and to standardize guidance around CLS-safe Suspense fallbacks across related error pages.
Changes:
- Reframes
prefetch = 'allow-runtime'as an optional enhancement (runtime prefetching of request data) rather than a way to address the dev<Link prefetch={true}>warning, and adds a clarifying “Good to know” callout. - Adds consistent CLS guidance + a canonical deep-link to the Streaming guide’s CLS section across several
blocking-prerender-*error pages.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| errors/blocking-prerender-random.mdx | Adds CLS-safe fallback guidance link in the Trade-off section. |
| errors/blocking-prerender-random-client.mdx | Adds CLS-safe fallback guidance link in the Trade-off section. |
| errors/blocking-prerender-current-time.mdx | Expands Trade-off to include CLS-safe fallback guidance + link. |
| errors/blocking-prerender-current-time-client.mdx | Adds CLS-safe fallback guidance link in the Trade-off section. |
| errors/blocking-prerender-crypto.mdx | Expands Trade-off to include CLS-safe fallback guidance + link. |
| errors/blocking-prerender-crypto-client.mdx | Adds CLS-safe fallback guidance link in the Trade-off section. |
| docs/01-app/02-guides/adopting-partial-prefetching.mdx | Clarifies allow-runtime vs partial (warning/opt-in) and updates audit table wording accordingly. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
|
All broken links are now fixed, thank you! |
![vercel[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
aurorascharff
changed the title
aurorascharff
changed the title
aurorascharff
added a commit
that referenced
this pull request
Jun 23, 2026
1 task
aurorascharff
added a commit
that referenced
this pull request
Jun 23, 2026
### What Driven by three friction logs from agents running `next-cache-components-adoption` against starting points the skill silently assumed. - Restructure `## requires` as a labeled checklist: **App Router project**, **Next.js 16.3 or later**, **No incompatible config keys**. Each item names what's checked, what the failure mode is, and where to resolve it. - Hoist the **No green baseline before the flag** note out of the prereq pile into a separate `### notes` block (alongside **Offline docs**), so a reader scanning prereqs doesn't conflate it with a hard requirement. - Tighten the codemod block: explain `@canary`'s necessity in one line so an agent hitting `Invalid transform choice` from `@latest` knows the workaround. ### Why Three friction logs each hit a different version of the same gap: - **react.dev migration**: agent ran codemod with `@latest` (16.2.9) → `Invalid transform choice` → applied transform by hand. - **Marketing-site case**: agent built the spec with `revalidate` exports, codemod left them in, `cacheComponents: true` rejected the build. - **E-commerce case**: `experimental.dynamicIO`/`useCache` left in `next.config` → fatal config error. In each case the skill *technically* said what to do but it was buried. ### Related The migration-guide changes that were originally in this PR moved to [#94997](#94997). ### Type of Change - [x] Documentation (adds or changes documentation) <!-- NEXT_JS_LLM_PR -->
icyJoseph
reviewed
Jun 23, 2026
icyJoseph
reviewed
Jun 23, 2026
icyJoseph
reviewed
Jun 23, 2026
icyJoseph
approved these changes
Jun 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Docs-only follow-ups for Cache Components and Partial Prefetching, from agent migration friction logs and Joseph's review of #95082.
adopting-partial-prefetching.mdx— reframe theallow-runtimerow in the audit table (it's an enhancement, not the<Link prefetch={true}>warning fix; the per-route opt-in isprefetch = 'partial').migrating-to-cache-components.mdx— split the## Enable Cache Componentssection into before-flag (removedynamic/revalidate/fetchCache) and after-flag (translaterevalidate,fetchCache,unstable_cache,fetchcache options) steps. Flag therevalidateTagsecond-argument requirement, with a Before / After example. Add two Good-to-know callouts: off-gridrevalidatevalues map to the closestcacheLifeprofile;instant = falseis allowed-to-block, not forced-dynamic.blocking-prerender-current-time/-random/-crypto(and their-clientsiblings) — drop the misleading "Don't want this validation?" opt-out section.instant = falseis an instant-navigation knob and doesn't suppress sync-IO prerender errors.blocking-prerender-*pages — standardize the CLS fallback callout so they all link the canonical section.Why?
Friction logs surfaced four recurring misreads:
prefetch = 'allow-runtime'to silence the<Link prefetch={true}>warning. The docs implied it would.dynamicremoval withunstable_cachetranslation, so it wasn't clear which had to happen before the flag and which after.revalidateTagnow requires a cache profile, but the on-demand revalidation section didn't say so.