Skip to content

Commit 6c5f3d5

Browse files
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 -->
1 parent 8cbc926 commit 6c5f3d5

20 files changed

Lines changed: 746 additions & 396 deletions

‎.agents/skills/insight-error-page/SKILL.md‎

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: insight-error-page
3-
description: Write or audit an insight-kind error page for the Next.js dev overlay. Use when creating a new `errors/<slug>.mdx` page, auditing an existing one, or checking that a page matches the framework fix cards. Covers page structure, title alignment, FixOption cards with Copy AI prompt button, code snippets, terminology verification against canonical docs, and Vercel technical writing style.
3+
description: Write or audit an insight-kind error page for the Next.js dev overlay. Use when creating a new `errors/<slug>.mdx` page, auditing an existing one, or checking that a page matches the framework fix cards. Covers page structure, title alignment, FixCard cards with Copy prompt button, code snippets, terminology verification against canonical docs, and Vercel technical writing style.
44
metadata:
55
internal: true
66
---
@@ -56,7 +56,7 @@ kind: insight
5656
5757
## Ways to fix this
5858
59-
<FixOption /> cards — one per framework card, in framework order
59+
<FixCardGrid> wrapping one <FixCard /> per framework card, in framework order
6060
6161
## <Card 1 title>
6262
Choose this fix when ...
@@ -76,7 +76,8 @@ kind: insight
7676
## Don't want this validation?
7777
(canonical opt-out block — see "Don't want this validation?" rule below)
7878
79-
## Useful links
79+
## Related Insights
80+
(full list of every other insight-kind error page, current page omitted)
8081
```
8182

8283
## Rules (hard requirements)
@@ -91,14 +92,16 @@ kind: insight
9192
- **Always the same canonical block** across all insight pages (the `--debug-prerender` tip). Never put page-specific content here.
9293
- Useful page-specific tips go in Gotchas under the relevant fix section.
9394

94-
### `<FixOption>` cards
95+
### `<FixCard>` cards
9596

96-
- One per framework card, in the same order as the framework `FixCard[]` array.
97+
- Wrap all cards in a single `<FixCardGrid>` (the same component used in `docs/01-app/02-guides/instant-navigation.mdx`).
98+
- One `<FixCard />` per framework card, in the same order as the framework `FixCard[]` array.
9799
- `title` = card title from framework, **verbatim**. If it reads awkward as a heading, change the framework first — never the docs.
98100
- `href` = `#` + the auto-slug of the title (e.g. "Generate on every request" → `#generate-on-every-request`). This must match what the heading auto-generates.
99-
- `group` = card group from framework (`dynamic`, `cache`, `client`, `stream`, `defer`, `measure`, `block`, `render`, `silence`).
100-
- Children = one-sentence plain-prose summary. **No inline code**, no API names in backticks, no snippets. Save technical detail for the section body.
101-
- **No `prompt` prop.** The "Copy AI prompt" button builds the prompt dynamically at click time from the page URL and the card's `title` + `href`. The agent receives a prompt that points at the rule docs and names the fix — it then reads the docs page (the same one the user is on) for every constraint and code shape. That is why this skill exists: the docs page itself **is** the prompt's source of truth.
101+
- `group` = card group from framework (`dynamic`, `cache`, `client`, `stream`, `defer`, `measure`, `block`, `render`, `ignore`, `upgrade`, `disable`, `static`).
102+
- `snippets` = the same `snippets` array as the matching framework `FixCard` in `instant-guidance-data.ts`. Copy it verbatim. No description prose lives on the card — the snippets carry the visual.
103+
- Self-close the tag (`<FixCard ... />`). The card has no children.
104+
- **No `prompt` prop.** The "Copy prompt" button builds the prompt dynamically at click time from the page URL and the card's `title` + `href`. The agent receives a prompt that points at the rule docs and names the fix — it then reads the docs page (the same one the user is on) for every constraint and code shape. That is why this skill exists: the docs page itself **is** the prompt's source of truth.
102105

103106
### `## <Fix>` sections
104107

@@ -124,8 +127,8 @@ kind: insight
124127

125128
- Framing paragraph: link to sibling pages (client ↔ server counterpart, parallel API families).
126129
- Gotchas: link to the `-client` page when warning about inline render in Client Components.
127-
- Useful links: keep it short (typically 2–6 entries). Sibling error pages + the canonical [Ensuring instant navigations](/docs/app/guides/instant-navigation) guide + 1–3 API references central to the fixes but not already inline-linked throughout the body. Do not re-list every API the body mentions — those are inline-linked at first use and the section is for follow-on navigation, not an index.
128-
- Every API reference and file convention must be inline-linked throughout, not reserved for Useful Links.
130+
- Related Insights: the full list of every other insight-kind error page, current page omitted. This is an index of the Insight family, not a curated short list. Order: body errors → metadata/viewport → unstable-value errors (server then client) → navigation Insights. Do not add API references or guides to this section; those belong inline in the body where relevant.
131+
- Every API reference and file convention must be inline-linked throughout, not reserved for the Related Insights section.
129132
- **Cross-page pattern linking**: When a fix on one page is covered in depth on a sibling page, show only the most common pattern inline and link out to the sibling for the full set. For example, a server page's "Render on the client" fix shows one client pattern and links to the `-client` page; a client page's "Other options" section bridges to the server page's cache fix. Don't duplicate entire sections across sibling pages — keep each page lean and let the sibling be the canonical reference.
130133
- **First-party only**: link only to `nextjs.org/docs/*`, `react.dev/*`, `developer.mozilla.org/*`, and other canonical first-party references. **Never** link to personal blogs, community write-ups, conference talks, X/Bluesky posts, GitHub gists, or any third-party source — including the page author's own blog. If a third-party post inspired a pattern, internalize the idea and write it in our own voice without citation. Sibling error pages, our own docs, and primary API specs are the only acceptable destinations.
131134

@@ -166,7 +169,7 @@ After the pattern snippets, include a "Use either pattern when:" bulleted list (
166169

167170
### Don't want this validation?
168171

169-
Every insight page ends (just before `## Useful links`) with the canonical opt-out block. It teaches the reader how to silence validation per-segment, subtree-wide, and app-wide, since instant-navigation validation runs by default in Cache Components apps. Copy verbatim:
172+
Every insight page ends (just before `## Related Insights`) with the canonical opt-out block. It teaches the reader how to silence validation per-segment, subtree-wide, and app-wide, since instant-navigation validation runs by default in Cache Components apps. Copy verbatim:
170173

171174
```mdx
172175
## Don't want this validation?
@@ -196,12 +199,14 @@ When auditing an existing page, check every item:
196199
- [ ] `title` = literal dev-overlay headline (from factory function), no period
197200
- [ ] `kind: insight` in frontmatter
198201
- [ ] Good to Know = the canonical `--debug-prerender` block (no page-specific content)
199-
- [ ] One `<FixOption>` per framework card, in framework order
200-
- [ ] Every `<FixOption>` `title` = card title verbatim
201-
- [ ] Every `<FixOption>` `href` = auto-slug of the heading
202-
- [ ] Every `<FixOption>` `group` matches framework card group
203-
- [ ] No `prompt` prop on any `<FixOption>` — the copy button generates the prompt from `title` + `href` + the page URL
204-
- [ ] `<FixOption>` children: plain prose, no backticks, no inline code
202+
- [ ] All cards wrapped in a single `<FixCardGrid>`
203+
- [ ] One `<FixCard />` per framework card, in framework order
204+
- [ ] Every `<FixCard />` `title` = card title verbatim
205+
- [ ] Every `<FixCard />` `href` = `#` + auto-slug of the heading
206+
- [ ] Every `<FixCard />` `group` matches framework card group
207+
- [ ] Every `<FixCard />` `snippets` = the framework card's `snippets` array, verbatim
208+
- [ ] No `prompt` prop on any `<FixCard />` — the copy button generates the prompt from `title` + `href` + the page URL
209+
- [ ] `<FixCard />` is self-closing (no children, no description prose)
205210
- [ ] Every `## <Fix>` heading = card title verbatim
206211
- [ ] Every fix section has `### Patterns`, `### Trade-off`, `### Gotchas`
207212
- [ ] No "Default." labels on patterns
@@ -210,9 +215,9 @@ When auditing an existing page, check every item:
210215
- [ ] Code snippets are valid React (no inline `Math.random()` during render in Client Components)
211216
- [ ] `useState(() => Math.random())` warned against in Gotchas
212217
- [ ] All API references inline-linked throughout
213-
- [ ] Sibling pages cross-linked in framing paragraph + Useful links
214-
- [ ] Useful links section is short (typically 2–6 entries). Does not re-list APIs that are already inline-linked in the body.
218+
- [ ] Sibling pages cross-linked in framing paragraph (inline body links carry the bulk of API references)
215219
- [ ] `## Don't want this validation?` section present, verbatim per the canonical block
220+
- [ ] `## Related Insights` section present, listing every other insight-kind error page (current page omitted)
216221
- [ ] Upstream `errors/<slug>.mdx` content preserved (relocated to Gotchas or Other options if needed)
217222
- [ ] Terminology matches canonical docs (verified, not assumed)
218223
- [ ] Vercel technical writing style applied (no banned words, active voice, sentence-case headings)

‎docs/01-app/02-guides/instant-navigation.mdx‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,6 @@ Cache Components validates this route automatically in development. If something
177177
{ text: 'async function Posts() {' },
178178
{ text: ' "use cache"', highlight: true },
179179
{ text: ' return <List items={…} />' },
180-
{ text: '}' },
181180
]}
182181
/>
183182
<FixCard
@@ -192,7 +191,7 @@ Cache Components validates this route automatically in development. If something
192191
/>
193192
</FixCardGrid>
194193

195-
> **Good to know:** Each fix card links to a detailed walkthrough with patterns, code samples, and trade-offs. Click a card to dive in.
194+
> **Good to know:** Each fix card links to a detailed walkthrough with patterns, code samples, and trade-offs. Click a card to dive in, or use **Copy prompt** to hand the fix to your agent. See [AI workflow](#ai-workflow) for the loop.
196195
197196
Validation runs on every page load using the real request from your browser, so dynamic params like `[slug]` are checked against actual values as you navigate.
198197

‎docs/01-app/02-guides/migrating-to-cache-components.mdx‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,6 @@ Cache Components validates your routes in development and surfaces errors and in
249249
{ text: 'async function Posts() {' },
250250
{ text: ' "use cache"', highlight: true },
251251
{ text: ' return <List items={…} />' },
252-
{ text: '}' },
253252
]}
254253
/>
255254
<FixCard

‎errors/blocking-prerender-client-hook.mdx‎

Lines changed: 39 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -27,27 +27,31 @@ During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering)
2727

2828
`useSearchParams` triggers this error on any prerendered route because search params come from the request URL. The other four hooks trigger it when the route has dynamic params and is rendered per-request.
2929

30-
Server-side request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers)) have different fixes. See [Next.js encountered runtime data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-runtime). For unstable values like [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in Client Components, see [Next.js encountered the unstable value Math.random() in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-random-client).
30+
Server-side request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers)) have different fixes. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime). For unstable values like [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in Client Components, see [Next.js encountered the unstable value Math.random() in a Client Component](/docs/messages/blocking-prerender-random-client).
3131

3232
## Ways to fix this
3333

34-
<FixOption
35-
group="stream"
36-
href="#wrap-in-or-move-into-suspense"
37-
title="Wrap in or move into Suspense"
38-
>
39-
Wrap the component that calls the hook in a Suspense boundary so Next.js can
40-
prerender a fallback while the runtime value loads.
41-
</FixOption>
42-
43-
<FixOption
44-
group="block"
45-
href="#allow-blocking-route"
46-
title="Allow blocking route"
47-
>
48-
Opt the segment out of instant-navigation validation. The route renders on
49-
every request.
50-
</FixOption>
34+
<FixCardGrid>
35+
<FixCard
36+
group="stream"
37+
title="Wrap in or move into Suspense"
38+
href="#wrap-in-or-move-into-suspense"
39+
snippets={[
40+
{ text: '<Suspense fallback={…}>', highlight: true },
41+
{ text: ' <SidebarNav />' },
42+
{ text: '</Suspense>', highlight: true },
43+
]}
44+
/>
45+
<FixCard
46+
group="block"
47+
title="Allow blocking route"
48+
href="#allow-blocking-route"
49+
snippets={[
50+
{ text: '// page.tsx or layout.tsx' },
51+
{ text: 'export const instant = false', highlight: true },
52+
]}
53+
/>
54+
</FixCardGrid>
5155

5256
## Wrap in or move into Suspense
5357

@@ -264,3 +268,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
264268
- **Entire app**: set [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. This limits validation to segments that explicitly export `instant`.
265269

266270
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
271+
272+
## Related Insights
273+
274+
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
275+
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
276+
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
277+
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
278+
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
279+
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
280+
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
281+
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
282+
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
283+
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
284+
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
285+
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
286+
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
287+
- [Unrendered segment](/docs/messages/instant-unrendered-segment)

0 commit comments

Comments
 (0)