Unverified Commit e8a2dd17 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

skill(cc-adoption): add dev-only validation sweep reference (#96057)

### What?

Add an optional post-adoption reference to the Cache Components adoption
skill, `references/dev-only-validations.md`, and point to it from the
skill's further reading.

### Why?

After adoption the build passes, but dev validation (default
`validationLevel: 'warning'`) still raises instant-navigation insights
on every page load that never fail the build. The skill had no recipe
for sweeping them, so this closes that gap as a recommended next step,
offered as the smaller path to instant navigation for users who don't
want to adopt Partial Prefetching.

### How?

The reference details the loop: reuse the `next-dev-loop` preflight,
load each route in `next dev`, read the Insights tab and dev log, and
fix. The mechanics mirror the tested `next-partial-prefetching-adoption`
skill (dev log record, amber Insights tab, `get_errors` not
`get_request_insights`, webpack fallback). The further-reading section
now recommends the sweep and drops the standalone Prefetching bullet,
which the Partial Prefetching adoption skill already carries.
parent ba55bd63
...@@ -229,8 +229,7 @@ When the loop has run on every feature — every remaining `instant = false` sit ...@@ -229,8 +229,7 @@ When the loop has run on every feature — every remaining `instant = false` sit
The work below is optional and lives in the docs — link the user to them and let them decide which to take on next. Don't walk these through inside this skill. The work below is optional and lives in the docs — link the user to them and let them decide which to take on next. Don't walk these through inside this skill.
- [Instant navigation](https://nextjs.org/docs/app/guides/instant-navigation) — dev-only validation warnings the overlay raises on client navigation. Same shape as the blocking-prerender errors you cleared in step 2; the guide covers the per-warning details. Recommend it next if the user wants navigations to actually be instant (a passing build doesn't guarantee that — a `<Suspense>` above the shared layout caught the page-load case but doesn't cover client navigation). - [Sweep for more instant navigations](./references/dev-only-validations.md) — an optional follow-up once adoption is done, never required. A passing build is not the last word, because dev validates every route on each page load (simulating both page loads and client navigations) and catches what the build's first-error exit and descendant shadowing skipped. Offer it as the smaller path to instant navigation for a user who doesn't want to adopt Partial Prefetching. Adopting Partial Prefetching (below) runs the same kind of loop and meets these insights anyway, so recommend both and let the user pick which, or whether. The reference is the loop to execute.
- [`next-partial-prefetching-adoption`](https://github.com/vercel/next.js/tree/canary/skills/next-partial-prefetching-adoption) — the follow-up skill that adopts Partial Prefetching: it enables `partialPrefetching` and audits every `<Link prefetch={true}>` against a decision table (or adopts incrementally with the flag off, driven by the `link-prefetch-partial` insight). It sequences this the same way this skill sequences Cache Components, but the insights are dev-only, so it's a browser click-through, not a build loop. Recommended after instant navigation, since those fixes feed directly into how much of each route the shell can prefetch. Concepts live in the [Adopting Partial Prefetching guide](https://nextjs.org/docs/app/guides/adopting-partial-prefetching). - [`next-partial-prefetching-adoption`](https://github.com/vercel/next.js/tree/canary/skills/next-partial-prefetching-adoption) — the follow-up skill that adopts Partial Prefetching: it enables `partialPrefetching` and audits every `<Link prefetch={true}>` against a decision table (or adopts incrementally with the flag off, driven by the `link-prefetch-partial` insight). It sequences this the same way this skill sequences Cache Components, but the insights are dev-only, so it's a browser click-through, not a build loop. Recommended after instant navigation, since those fixes feed directly into how much of each route the shell can prefetch. Concepts live in the [Adopting Partial Prefetching guide](https://nextjs.org/docs/app/guides/adopting-partial-prefetching).
- [Prefetching](https://nextjs.org/docs/app/guides/prefetching) and [Runtime prefetching](https://nextjs.org/docs/app/guides/runtime-prefetching) — broader prefetching reference. Runtime prefetching extends the static shell with per-session content; reach for it when a route's shell is too thin to be useful and Partial Prefetching alone doesn't cover the gap.
- [Prevent regressions with e2e tests](https://nextjs.org/docs/app/guides/instant-navigation#prevent-regressions-with-e2e-tests) — the `@next/playwright` [`instant()`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#testing-instant-navigation) helper asserts on the UI that's available immediately on navigation, so regressions surface in CI. Recommend it once a route is instant: `next-dev-loop` confirms it _now_; an `instant()` test keeps it that way. - [Prevent regressions with e2e tests](https://nextjs.org/docs/app/guides/instant-navigation#prevent-regressions-with-e2e-tests) — the `@next/playwright` [`instant()`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#testing-instant-navigation) helper asserts on the UI that's available immediately on navigation, so regressions surface in CI. Recommend it once a route is instant: `next-dev-loop` confirms it _now_; an `instant()` test keeps it that way.
- [`next-cache-components-optimizer`](https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-optimizer) — a separate skill that grows each route's static shell so more of the page prerenders and less streams in. Pure optimization, not part of adoption. - [`next-cache-components-optimizer`](https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-optimizer) — a separate skill that grows each route's static shell so more of the page prerenders and less streams in. Pure optimization, not part of adoption.
# dev-only validation sweep
How to surface and fix the instant-navigation insights that a clean `next build` does not show. The [Instant navigation guide](https://nextjs.org/docs/app/guides/instant-navigation) is the canonical reference for the validation model this exercises.
## what the build misses
By default (`validationLevel: 'warning'`) Cache Components validates every Page and Default segment in `next dev`, and the insights land in the dev overlay's Insights tab, not the build. Validation runs on every page load using the real request, and for each route it independently checks the initial page load and client navigations at different points in the hierarchy. So a `<Suspense>` boundary that covers the page load can still leave a client navigation blocking, and a layout stays clean at build time while a descendant keeps its `instant = false`. The build stops at the first blocking route and does not raise this family by default. Loading each route in dev is what surfaces it.
## when to run it
After the Cache Components build is clean, not before. While the app is mid-adoption the build redboxes mask this, so a full clean build (every route `◐`, no errors) is the precondition. A quiet sweep is the expected result of a clean adoption, not a missing signal.
## the loop
Reuse the [`next-dev-loop`](https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop) preflight (Turbopack), then add one job. On a webpack app, drive a browser directly with `agent-browser` or Playwright instead. You lose the `/_next/mcp` cross-checks, not the insights, which still show in the overlay and the dev log.
1. Build a route queue from the last build's route table or the `app/` tree.
2. Load each route in `next dev` with a browser. A refresh or a link click both work, and validation simulates both the page-load and client-navigation cases on that load, so you do not need to click through every link by hand. Dynamic params are checked against the real values you visit, so hit a concrete `[slug]`, not the pattern.
3. Watch the dev log and the Insights tab. The dev log is the greppable record, one `Error: Route "...": Next.js encountered ...` line per insight with its `docs/messages/<slug>` link, and it reads the same on Turbopack and webpack. The Insights tab is amber and appears only once an insight fires, so a route with no tab is clean. Through `next-dev-loop`'s `/_next/mcp`, these come from `get_errors` and the overlay, not `get_request_insights`, which is the performance recorder and reports nothing here.
4. Open the linked page for each distinct insight and apply its fix (usually pull a `<Suspense>` boundary down to the read). Reload to confirm it clears.
## gotchas
- The overlay renders inside a shadow root (`nextjs-portal`), so accessibility-tree snapshots miss it. Read it through `shadowRoot`.
- No browser, no sweep. There is no build-only fallback for this family. Apply the static fix you can from the docs page (gate on type-check) and hand off the live confirmation.
## when this shrinks
Build-time instant validation is opt-in today (`experimental.instantInsights.validationLevel: 'experimental-error'`); the default `'warning'` surfaces in the overlay only. Once the build raises these reliably, the sweep collapses into reading `next build` output and this reference can shrink to that.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment