Unverified Commit 87a1c18e authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

test: preserve static params during Cache Components migration (#98209)

## Summary

Adds an agent eval covering migration of the legacy on-demand ISR
pattern: `force-static`, `revalidate`, and an empty
`generateStaticParams` result.

The assertions require the agent to enable Cache Components, preserve
the `generateStaticParams` export, and replace its empty result with at
least one parameter instead of deleting the function. The fixture also
runs the Cache Components adoption skill with the established 30-minute
timeout.

Updates the Cache Components migration guide to link each legacy route
segment config to its migration instructions. The `generateStaticParams`
section now explains that removing the export opts a dynamic route out
of ISR and links to the ISR with Cache Components guide.

## Eval results

### Before the guide change

| Treatment | Result | Duration | Behavior |
| --- | --- | ---: | --- |
| Baseline | Passed (1/1) | 482.9s | Preserved `generateStaticParams`
and returned a real seed. |
| Bundled docs / AGENTS.md | Failed (0/1) | 444.7s | Deleted
`generateStaticParams`, incorrectly treating omission as equivalent to
returning an empty array. |
| Cache Components skill | Passed (1/1) | 527.6s | Preserved
`generateStaticParams` and returned a real seed. |

The failed treatment was classified as a model failure. It read the
bundled migration guide but concluded that deleting
`generateStaticParams` preserved the defer-all-paths-to-runtime
behavior. The eval catches that loss of on-demand ISR semantics.

The full run used the identical fixture immediately before its numeric
identifier was changed from `agent-044` to the final `agent-054` name.
The fixture and assertions were unchanged.

### After the guide change

| Treatment | Result | Duration | Behavior |
| --- | --- | ---: | --- |
| Baseline | Passed (1/1) | 739.5s | Preserved `generateStaticParams`,
returned `FEATURED_EVENT_SLUG`, and compared the migrated route with the
original behavior. |
| Bundled docs / AGENTS.md | Passed (1/1) | 393.2s | Read the revised
migration and ISR guides, preserved `generateStaticParams`, and returned
`FEATURED_EVENT_SLUG`. |
| Cache Components skill | Passed (1/1) | 547.3s | Preserved
`generateStaticParams`, returned `FEATURED_EVENT_SLUG`, and verified the
build and representative routes in development. |

In the first controlled pair, the bundled-docs treatment changed from
failing to passing. Its final migration kept the route eligible for ISR,
preserved the 60-second revalidation behavior with `use cache` and
`cacheLife`, and produced a passing build.

### Additional variance check

The bundled-docs treatment was run once more against each guide version:

| Guide version | First sample | Second sample | Observed result |
| --- | --- | --- | --- |
| Before this change | Failed (444.7s) | Passed (455.6s) | 1/2 passed |
| After this change | Passed (393.2s) | Passed (425.2s) | 2/2 passed |

The second pre-change sample shows that the previous wording could still
lead the agent to the correct migration. The revised wording passed both
observed samples, suggesting that the explicit ISR consequence improves
reliability. Two samples per version are not enough to claim a stable
pass rate.

## Verification

- `pnpm --filter=next build`
- `pnpm eval agent-054-cache-components-empty-static-params --dry`
- `pnpm eval agent-054-cache-components-empty-static-params`

<!-- NEXT_JS_LLM -->
parent fb4c4988
...@@ -89,7 +89,7 @@ export const instant = false ...@@ -89,7 +89,7 @@ export const instant = false
You don't have to migrate every route at once. `instant = false` lets you get the whole app building and running first, then convert routes one at a time: You don't have to migrate every route at once. `instant = false` lets you get the whole app building and running first, then convert routes one at a time:
1. **Enable the flag and remove the route segment configs** (`dynamic`, `revalidate`, `fetchCache`). Routes that still render instantly need no further work. 1. **Enable the flag and migrate each route segment config.** Follow the relevant sections below for [`dynamic = "force-dynamic"`](#dynamic--force-dynamic), [`dynamic = "force-static"`](#dynamic--force-static), [`revalidate`](#revalidate), and [`fetchCache`](#fetchcache). For routes with dynamic params, also follow the [`generateStaticParams`](#generatestaticparams-and-dynamicparams) guidance. Routes that still render instantly need no further work.
2. **Opt out the routes that aren't ready.** Where an insight or error appears, set `instant = false` on the segment that raised it. To do this in one pass across the whole app, run the [`cache-components-instant-false`](/docs/app/guides/upgrading/codemods#cache-components-instant-false) codemod, which adds the opt-out to every `page`, `layout`, and `default` that doesn't already declare `instant`: 2. **Opt out the routes that aren't ready.** Where an insight or error appears, set `instant = false` on the segment that raised it. To do this in one pass across the whole app, run the [`cache-components-instant-false`](/docs/app/guides/upgrading/codemods#cache-components-instant-false) codemod, which adds the opt-out to every `page`, `layout`, and `default` that doesn't already declare `instant`:
```bash filename="Terminal" ```bash filename="Terminal"
...@@ -569,6 +569,8 @@ Cache Components changes how [dynamic routes](/docs/app/api-reference/file-conve ...@@ -569,6 +569,8 @@ Cache Components changes how [dynamic routes](/docs/app/api-reference/file-conve
**Returning an empty array now errors.** Without Cache Components, returning `[]` defers every path to the first runtime visit. With Cache Components, [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) must return at least one param so Next.js can prerender the route and validate it produces a non-empty [static shell](/docs/app/glossary#static-shell). An empty array raises [`empty-generate-static-params`](/docs/messages/empty-generate-static-params). **Returning an empty array now errors.** Without Cache Components, returning `[]` defers every path to the first runtime visit. With Cache Components, [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) must return at least one param so Next.js can prerender the route and validate it produces a non-empty [static shell](/docs/app/glossary#static-shell). An empty array raises [`empty-generate-static-params`](/docs/messages/empty-generate-static-params).
Keep `generateStaticParams` and return at least one real param. Removing the export opts the route out of ISR, so Next.js renders it on every request, even when it uses `use cache` for data. Read [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) to learn how `generateStaticParams` prerenders dynamic routes and upgrades unlisted paths after their first visit.
```tsx filename="app/blog/[slug]/page.tsx" switcher ```tsx filename="app/blog/[slug]/page.tsx" switcher
// Before - defer all paths to runtime // Before - defer all paths to runtime
export async function generateStaticParams() { export async function generateStaticParams() {
......
...@@ -6,5 +6,9 @@ ...@@ -6,5 +6,9 @@
"agent-047-adopt-cache-components": { "agent-047-adopt-cache-components": {
"skills": ["next-cache-components-adoption"], "skills": ["next-cache-components-adoption"],
"timeout": 1800 "timeout": 1800
},
"agent-054-cache-components-empty-static-params": {
"skills": ["next-cache-components-adoption"],
"timeout": 1800
} }
} }
/**
* Preserve on-demand ISR when adopting Cache Components
*
* The starting route uses the previous on-demand ISR pattern:
* `force-static`, `revalidate`, and an empty `generateStaticParams` result.
* Cache Components rejects an empty result, but deleting the function changes
* the route to request-time rendering. The migration must retain the export
* and give it at least one param so other params can still be cached on demand.
*/
import { expect, test } from 'vitest'
import { readFileSync } from 'fs'
import { join } from 'path'
const config = readFileSync(join(process.cwd(), 'next.config.ts'), 'utf-8')
const eventPage = readFileSync(
join(process.cwd(), 'app/events/[slug]/page.tsx'),
'utf-8'
)
const eventPageWithoutComments = eventPage
.replace(/\/\*[\s\S]*?\*\//g, '')
.replace(/\/\/.*$/gm, '')
test('enables Cache Components', () => {
expect(config).toMatch(/cacheComponents\s*:\s*true/)
})
test('preserves generateStaticParams for on-demand ISR', () => {
expect(eventPageWithoutComments).toMatch(
/export\s+(?:(?:async\s+)?function\s+generateStaticParams\b|const\s+generateStaticParams\s*=)/
)
})
test('generateStaticParams no longer returns an empty array', () => {
expect(eventPageWithoutComments).not.toMatch(
/generateStaticParams[\s\S]*?return\s*\[\s*\]/
)
})
Migrate this app to Cache Components incrementally. Make the smallest safe first change that enables Cache Components, keeps the build passing, and preserves the current rendering and caching behavior.
import { notFound } from 'next/navigation'
import { getEvent } from '../../../lib/events'
export const dynamic = 'force-static'
export const revalidate = 60
export function generateStaticParams() {
return []
}
export default async function EventPage({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const event = await getEvent(slug)
if (!event) notFound()
return (
<main>
<h1>{event.title}</h1>
<p>{event.description}</p>
</main>
)
}
import type { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
import Link from 'next/link'
export default function HomePage() {
return (
<main>
<h1>Events</h1>
<Link href="/events/launch-day">View the featured event</Link>
</main>
)
}
export const FEATURED_EVENT_SLUG = 'launch-day'
const events = {
[FEATURED_EVENT_SLUG]: {
title: 'Launch Day',
description: 'Follow the launch as it happens.',
},
} as const
export async function getEvent(slug: string) {
return events[slug as keyof typeof events] ?? null
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {}
export default nextConfig
{
"private": true,
"type": "module",
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
},
"dependencies": {
"next": "^16",
"react": "19.1.0",
"react-dom": "19.1.0"
},
"devDependencies": {
"@types/node": "^20",
"@types/react": "^19",
"@types/react-dom": "^19",
"@vitejs/plugin-react": "^4.4.1",
"typescript": "^5",
"vite-tsconfig-paths": "^5.1.4",
"vitest": "^3.1.3"
}
}
{
"compilerOptions": {
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"strict": true,
"noEmit": true,
"esModuleInterop": true,
"module": "esnext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve",
"incremental": true,
"plugins": [
{
"name": "next"
}
],
"paths": {
"@/*": ["./*"]
},
"target": "ES2017"
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
"exclude": ["node_modules"]
}
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