Add instant-navs skill#94152
Draft
feedthejim wants to merge 10 commits into
Draft
Conversation
Adds a user-facing built-in skill that teaches App Router Instant Navigation and PPR shell-capture patterns. Covers the Playwright-first validation ladder, ten composition rules, shell-capture rules, test-oracle traps, a debug ladder, and a boundary decision table. Includes three references (diagnostic-loop, playwright-verification, react-suspense-composition) and a diagnostic-extraction script. Bundled into next/dist/skills/instant-navs/ via packages/next/taskfile.js copy_skills. Signed-off-by: Jimmy Lai <laijimmy0@gmail.com>
Contributor
Failing CI jobsCommit: fda9e8a | About building and testing Next.js |
Contributor
Stats from current PR🟢 1 improvement
📊 All Metrics📖 Metrics GlossaryDev Server Metrics:
Build Metrics:
Change Thresholds:
⚡ Dev Server
📦 Dev Server (Webpack) (Legacy)📦 Dev Server (Webpack)
⚡ Production Builds
📦 Production Builds (Webpack) (Legacy)📦 Production Builds (Webpack)
📦 Bundle SizesBundle Sizes⚡ TurbopackClient Main Bundles
Server Middleware
Build DetailsBuild Manifests
📦 WebpackClient Main Bundles
Polyfills
Pages
Server Edge SSR
Middleware
Build DetailsBuild Manifests
Build Cache
🔄 Shared (bundler-independent)Runtimes
📎 Tarball URLCommit: fda9e8a |
Replaces internal Vercel/v0-team jargon with terms a vanilla Next.js user will understand on first read. Translations: oracle → (focused) test, geometry → layout dimensions / box model, locked shell → captured shell, released route/UI → loaded route/UI, chrome → shared layout, persistent chrome → persistent shared layout, Instant lock → shell capture / while the shell is captured. Per-file edits are pure language; no rule count or substantive guidance changed. Signed-off-by: Jimmy Lai <laijimmy0@gmail.com>
- Rename route segment config from `instant` to `unstable_instant` to match the actual zod schema (the schema strips unknown keys silently, so the old name compiled to a no-op). - Drop `rootParams()` framing; `next/root-params` exports named per-param getters, not an aggregate function. - Add a Version And Flag Requirements section with the minimum Next.js version, `cacheComponents`, `experimental.instantInsights`, `experimental.exposeTestingApiInProductionBuild`, and the test deps. - Tighten extract-instant-diagnostics.mjs regexes to match the actual backtick-wrapped `Could not validate \`unstable_instant\`` and `\`cookies()\` was called outside a request scope` strings. - Drop the stale "error does not point at the call site" note for `headers()` inside `after()`; the error names the route and remediation.
… panel - Expand the per-route `unstable_instant` config example with the granular escape hatches (`unstable_disableDevValidation`, `unstable_disableBuildValidation`, `unstable_disableValidation`) and the per-route `level` override. - Reorder the diagnostic-loop Escape Hatches as a ladder from smallest to largest opt-out so readers pick the least disruptive one first. - Point Source Priority at the dev overlay's Instant Navigation panel by name; it is the canonical surface for blocking-route diagnostics.
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
1 participant
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
Adds a built-in skill,
instant-navs, that teaches App Router InstantNavigation and PPR shell-capture patterns, fact-checked against Next.js
16.3 source. Two entry points:
the common trigger "client navigations to this route feel slow." Flip
instantInsights: { validationLevel: 'warning' }, navigate, read thepanel or stdout diagnostic, apply one boundary move, loop, exit on
fast second nav + clean stdout. No route marker, Playwright test, or
build required.
write the focused `@next/playwright` `instant()` test, and
optionally promote the route to `unstable_instant = { level:
'experimental-error' }` once the regression test exists.
Files:
composition rules, marker convention, acceptance criteria.
writing and auditing `@next/playwright` Instant tests.
Boundary Decision Table, Known Diagnostic Signatures, escape hatches.
layout, provider, fallback, shell-capture ownership patterns.
Also separates the published skill surface from the repo-local one
(`skills/README.md` declares `skills/` as the externally distributed
bundle; `.agents/skills/authoring-skills/SKILL.md` is scoped to
repo-local `.agents/skills/` only).
Why
App authors today reverse-engineer Instant Navigation from docs
scattered across PPR, Cache Components, `next/root-params`,
`generateStaticParams`, and `@next/playwright`. The skill
consolidates the composition rules and validation workflow in one
invocable artifact.
Most users arrive from "my page feels slow," not from a greenfield
adoption decision. Diagnose Slow Navigations is the headline so the
skill activates from the real trigger and offers a low-commitment fix
path before pushing toward the heavier test-and-lock-in flow.
Fact-Checked Against Source
`instant`. The zod schema is non-strict, so `instant` typos
compile to no-ops. The dev runtime sometimes suggests the wrong key
in blocking-route diagnostics; the skill calls this trap out at step
4 of Diagnose Slow Navigations.
(`packages/next/src/server/config.ts:1621`), applied unconditionally
even with no `experimental.instantInsights` block.
segment-scoped. A parent layout's `` around
`{children}` and a parent segment's `loading.tsx` both fail to
silence `blocking-route` for a child page's suspending data, even
though React's runtime fallback inheritance renders them correctly.
Sibling navigations within a shared layout re-render only the
changing leaf, so the boundary has to live in the suspending segment
for every navigation source to land on an instant shell.
`import { locale } from 'next/root-params'`), not an aggregate
`rootParams()` function.
Test plan
from explicit Instant Navigation / `@next/playwright` mentions.
in the `next/dist/skills/` bundle output.
App Router app with a planted blocker (cookies-above-shell,
uncached fetch, or useSearchParams-without-Suspense).
Follow-ups (not in this PR)
misleading when a parent layout has a Suspense whose fallback streams
correctly. The skill explains the actual rule (validation is
segment-scoped); the runtime message itself should be made more
precise in a separate framework PR.
agent sandboxes; a separate PR can wire that up.