hanzoai/next.js
2
0
Fork 0
mirror of https://github.com/hanzoai/next.js.git synced 2026-09-24 17:00:51 +00:00
Code Issues Packages Projects Releases Wiki Activity
34,723 Commits 3 Branches 3,979 Tags
0f01364309bd75ed6e7b2735dad400a3c9dfd1ff
Commit Graph
9 Commits
Author SHA1 Message Date
Aurora ScharffandGitHub 76628b4f9b [PP] Surface URL data during prefetching as an Instant insight with rule page (#95365) 
## What?

Adds the Instant Insight + rule page for the Partial Prefetching shell
validation (Janka's #95151): with `partialPrefetching` on, a route that
reads `params`/`searchParams` outside `<Suspense>` blocks the extraction
of the per-route **App Shell** that every link to the route shares.
Surfaced as an Instant insight (not a redbox), with two fix cards:
Stream (wrap in `<Suspense>`) · Allow blocking route (`instant =
false`).

The insight fires both at link-prefetch time and during a client-side
navigation, so it covers a `<Link prefetch>` into the route as well as a
plain client navigation to it.

Demos:

-
[99-link-params-gsp](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/99-link-params-gsp)
— `<Link prefetch>` to a `generateStaticParams` route that awaits
`params` unguarded.
-
[117-subnav-params](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/117-subnav-params)
— client-side navigation into a `[slug]` route that reads `params`
outside `<Suspense>`.
-
[118-subnav-search-params](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/118-subnav-search-params)
— client-side navigation into a route that reads `searchParams` outside
`<Suspense>`.

Follow-up: #95389 documents the route-side audit in the Adopting Partial
Prefetching guide (draft, to be coordinated).

## How?

- Family-wide polish across all 16 insight pages while aligning the new
one: consistent "Verifying the fix" wording, normalized `Learn more:`
link texts (target title for guides, bare code name for API references),
"App Shell" used consistently, CLS guidance reframed as "minimizing
layout shift", prose cleanups (no semicolons, no code-initial
sentences), and the insight-error-page skill updated to match.
- New `errors/instant-shell-url-data.mdx` rule page, structured like the
rest of the insight family (`blocking-prerender-client-hook`,
`instant-link-prefetch-partial`); added to every page's Related
Insights. New **URL data** glossary entry ("varies per link, not per
session"), linked from the page.
- `createLinkBodyErrorInNavigation` re-pointed to the page and
classified as a navigation-time insight (`inNavigation` → Instant tab)
using the shared `linkCards` fix cards.
- Common insight format for the message: headline "Next.js encountered
URL data outside of Suspense", consequence "may prevent the navigation
from being instant, leading to a slower user experience" ("may", since
boundaries or a runtime prefetch can still keep the navigation instant),
and the two fixes phrased as `[stream] Provide a placeholder with
<Suspense fallback={...}> around the data access` and `[block] Set
export const instant = false to allow a blocking route`. The shell
mechanics are explained on the docs page rather than in the headline.
- Second fix reframed from "Disable validation" (group `ignore`) to
**Allow blocking route** (group `block`), matching the
`blocking-prerender-*` family: `instant = false` marks the segment as
allowed to block rather than opting the route out of validation.
- Metadata/viewport variants: only the headline term is aligned ("link
data" → "URL data") plus a small grammar fix; framing, fix cards, and
docs URLs stay on the existing `-metadata-runtime`/`-viewport-runtime`
pages unchanged.
- `errors.json` regenerated append-only (codes 1407-1409), and the docs
opt-out wording updated to the new silence-free phrasing.
- e2e snapshots updated for all four configs (dev/start ×
default/partial-prefetching); unit tests for the matcher, cards,
classification, and `isInstantNavigationError`.

<!-- NEXT_JS_LLM_PR -->
 2026-07-08 04:04:01 +02:00
Aurora ScharffandGitHub 6c5f3d5775 Rename Copy as prompt to Copy prompt, convert FixOption to FixCard (#95309) 
## Why

Standardize the Insight fix UI across the dev overlay and docs, and
round out the docs side with a proper family index at the bottom of
every page.

## What

- Dev overlay: **Copy as prompt** -> **Copy prompt**; bumped the pill
padding to match the new docs button.
- Error pages (`errors/*.mdx`, 15 files): `<FixOption>` ->
`<FixCardGrid>`/`<FixCard>` with snippets copied verbatim from
`instant-guidance-data.ts`; all `https://preview.nextjs.org/docs/...`
URLs converted to relative `/docs/...`.
- Every Insight error page now ends with a `## Related Insights` index
listing the other 14 Insight pages (self omitted).
- `instant-navigation.mdx` and `migrating-to-cache-components.mdx`:
dropped the stray trailing `}` snippet line so guide cards match
dev-overlay heights; added a one-line Copy prompt note linking to
`#ai-workflow`.
- `insight-error-page` skill: replaced the "Useful links" guidance with
"Related Insights" (full family index, no API refs/guides) and matching
audit-checklist line.
- Minor cleanup in `instant-guidance-data.ts` (trimmed verbose JSDoc to
non-obvious bits).

## How

Paired with vercel/front#75443 which adds the Copy prompt button to
`<FixCard>` and deletes the legacy `<FixOption>`. `pnpm --filter=next
types` clean, 23 `instant-guidance-data` tests pass.

<!-- NEXT_JS_LLM_PR -->
 2026-07-01 10:34:06 -04:00
Aurora ScharffandGitHub 5ad38b43bc docs(insights): restructure error pages and link to preview docs (#95193) 
### 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 -->
 2026-06-26 14:12:19 +02:00
Aurora ScharffandGitHub f965c00411 Insights: drop irrelevant fix cards from instant errors (#94926) 
### Why?

Two Insight fix cards were misleading:

1. **`generateStaticParams` showed up on every runtime/client-hook
insight.** One error covers `cookies()` / `headers()` / `params` /
`searchParams`. GSP only applies to `params`; for the others it's noise.
Even for `params` it nudges devs to make the route static instead of
fixing the immediate error.
2. **`"use cache"` showed up on `connection()` triggers.** Caching
`connection()` is contradictory.

Both manifest on initial load and in-navigation (the fix-card sets are
shared).

### What?

1. **Drop the GSP card** from runtime + client-hook sets. Affects
[01-cookies-body](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/01-cookies-body),
[03-params-body](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/03-params-body),
[90-client-use-params](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/90-client-use-params),
[41-subnav-cookies](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/41-subnav-cookies),
[42-subnav-fetch](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/42-subnav-fetch).
2. **Filter `"use cache"`** when the cause is `connection()`. Affects
[05-connection-body](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/05-connection-body),
[08-connection-body-dynamic](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/08-connection-body-dynamic),
[31-connection-in-metadata](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/31-connection-in-metadata),
[33-connection-in-viewport](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/33-connection-in-viewport).
[06-uncached-fetch-body](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/06-uncached-fetch-body)
keeps the Cache card.

### How?

- `getCards()` filters the cache card when `cause === 'connection'`.
- New `deriveCauseFromCodeFrame()` helper detects `connection(` on the
highlighted code-frame line.
- `ParamClientHookDynamicError` collapsed into `ClientHookDynamicError`.
- CLI/build messages: dropped the GSP bullet; added `(does not apply to
\`connection()\`)` on the cache bullet.
- Docs: removed `For known params, prerender` sections; added a
connection caveat on dynamic/metadata-dynamic/viewport-dynamic pages.

<!-- NEXT_JS_LLM_PR -->
 2026-06-23 19:27:11 +02:00
Aurora ScharffandGitHub 0a518a84e9 instant: build fix-card Copy AI prompt dynamically from title + link (#94637) 
### What

The dev-overlay fix cards' `Copy AI prompt` button used to copy a
multi-paragraph instruction string baked into each card (71 prompts
across docs + runtime). This PR replaces that with a dynamic template
the button builds at click time:

```
Apply the [Stream] "Wrap in or move into Suspense" fix to the Next.js Insight raised in this project.

Steps:

1. The failing code is in the error block below — it may be a data-access call, a hook call, a metadata or viewport export, or a component. The fix applies to that exact code; don't touch unrelated files.

2. Read the rule docs at <rule-url> for the full Insight explanation, then read the fix section at <fix-url>. Pick the pattern under "### Patterns" that matches the failing code, then read "### Gotchas" before editing — they list constraints that are easy to miss. Use the canonical imports and code shape from the page; don't improvise variations.

3. Apply the chosen pattern to the code identified in step 1.

## Error Type
Blocking Route

## Error Message
Route "/01-cookies-body": ...
    at Page (app/01-cookies-body/page.tsx:4:26)

## Code Frame
> 4 |   const c = await cookies();
    |                          ^
...

Next.js version: 16.3.0-canary.47 (Turbopack)
```

### Why

Old verbatim prompts repeated what the docs already say and never
anchored the fix to the actual error. The new template:

- Names the chosen fix (group badge + title) so the agent picks the
right pattern.
- Points at the rule docs AND the specific fix anchor, with explicit
instructions to read `### Patterns` and `### Gotchas`.
- Prepends the live error block (same shape the existing 'Copy error
info' button emits) so the agent has the failing file, line, code frame,
and stack inline — no need to re-fetch the dev overlay.

### Changes

- `FixCard` type: `prompt?: string` → `copyable?: boolean`
- `CopyPromptButton`: takes `title + group + link + generateErrorInfo`,
builds the prompt
- Refactored `generateErrorInfo` from `errors.tsx` into a shared
`utils/generate-error-info.ts` so the existing 'Copy error info' button
and the fix-card 'Copy AI prompt' button format the error block
identically
- 14 error MDX pages: every `prompt={...}` removed (36 strings)
- `instant-guidance-data.ts`: every `prompt: '...'` → `copyable: true`
(35 strings)
- Skill (`.agents/skills/insight-error-page/SKILL.md`): updated

### Pairs with

vercel/front#73087 — same template in the docs-site `<FixOption>`
(without the error block, since there's no live error on a docs page).

<!-- NEXT_JS_LLM_PR -->
 2026-06-10 13:23:11 +02:00
Aurora ScharffandGitHub 23b1977efc docs: remove unstable_disableValidation recommendations (#94608) 
### What?

Removes `unstable_disableValidation` recommendations from all 14
insight-kind error pages and the `generateViewport` API reference. The
key on `unstable_instant`'s object form is not going to ship as a
recommended public API.

### Why?

Each error page's **"Don't want this validation?"** block previously
listed three opt-out levels:

1. **One segment** — `export const unstable_instant = false`
2. ~~**Layout and its children** — `export const unstable_instant = {
unstable_disableValidation: true }`~~ ← dropped
3. **Entire app** — `experimental.instantInsights.validationLevel:
'manual-warning'`

Dropping the middle bullet aligns the docs with the public-API surface
we intend to keep.

### How?

- Removed the `Layout and its children` bullet across 14 `errors/*.mdx`
pages.
- Removed the now-broken `See [Don't want this validation?] for the
subtree-wide opt-out` reference in the in-body **Gotchas** sections.
- Updated the `generate-viewport.mdx` API reference to drop the same
dangling reference.
- Framework source (`unstable_disableValidation` parsing in
`app-segment-config.ts` and runtime handling in `instant-config.tsx`) is
unchanged — that's a separate framework concern.

<!-- NEXT_JS_LLM_PR -->
 2026-06-09 23:15:19 +02:00
Josh StoryandGitHub d424aa8ec4 Stabilize unstable_instant (#94578) 
This API has experimental modes for build validation but the dev
validation is going to be stable in the next release.
 2026-06-09 13:50:25 -07:00
Aurora ScharffGitHubJosh Story
 		5b99d26df8 instant: polish client-hook overlay wording, cards, and docs links (#94496) 
### What?

Polishes the dev-overlay UX for the client-hook prerender error after
Josh's framework fix landed in
[#94494](https://github.com/vercel/next.js/pull/94494). The overlay now
names the hook in the headline and shows per-hook fix cards.

### Why?

Different hooks need different fixes. `useSearchParams` always suspends,
but `generateStaticParams` doesn't apply to it. `useParams` is the only
hook GSP resolves at build time. `usePathname` and
`useSelectedLayoutSegment(s)` need a Suspense boundary or the `[block]`
export.

### How?

- Headline now reads "Next.js encountered URL data `useX()` in a Client
Component outside of `<Suspense>`", matching the body factory wording.
- Per-hook card sets in `instant-guidance-data.ts`: `useSearchParams` →
Stream + Block; `useParams` → Stream + GSP + Block; `usePathname` /
`useSelectedLayoutSegment(s)` → Stream + Block.
- Build-time message in `ClientHookDynamicError` /
`ParamClientHookDynamicError` matches the overlay card set.
- Companion docs page:
[vercel/front#72622](https://github.com/vercel/front/pull/72622).

### Verification

Demo scenarios on the [error-messages-overhaul test
app](https://error-messages-overhaul-ibsl.labs.vercel.dev/):
[88-client-use-pathname](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/88-client-use-pathname),
[89-client-use-search-params](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/89-client-use-search-params),
[90-client-use-params](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/90-client-use-params),
[91-client-use-selected-layout-segment](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/91-client-use-selected-layout-segment),
[92-client-use-selected-layout-segments](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/92-client-use-selected-layout-segments).

<!-- NEXT_JS_LLM_PR -->

---------

Co-authored-by: Josh Story <[email protected]>
 2026-06-09 15:20:11 +02:00
Aurora ScharffandGitHub 2cc99c73b5 docs: move insight error pages from vercel/front to canary (#94564) 
### What?

Moves 14 insight-kind error pages from
`vercel/front/apps/next-site/content/errors-extra/` into this repo's
`errors/` directory.

### Why?

`nextjs.org`'s sync pipeline already clones `errors/` from canary on
every deploy. `errors-extra/` is meant for in-flight drafts. These pages
have stabilized, so they belong with the framework code they describe.

This unblocks Docs Link Validation in #94496: cross-links from this
repo's API docs (`cookies.mdx`, `headers.mdx`, `use-params.mdx`,
`use-pathname.mdx`, `generate-metadata.mdx`, `generate-viewport.mdx`,
etc.) to `/docs/messages/blocking-prerender-*` now resolve.

### How?

Copied each `.mdx` verbatim. No content changes. Frontmatter (`kind:
insight`) routes them through the FixOption renderer. Follow-up PR in
`vercel/front` will remove the `errors-extra/` copies; until then the
override wins on slug collision but the content is byte-identical.

<!-- NEXT_JS_LLM_PR -->
 2026-06-09 01:01:05 +02:00