Unverified Commit 2aaa6e81 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: preserve route behavior during Cache Components adoption (#98275)

## Summary

- Explain that removing `dynamic = 'force-dynamic'` moves a route from
full request-time rendering to Cache Components' Partial Prerendering
model, then document the choices for its request-time work.
- Preserve routes that previously used `dynamic = 'force-static'` or
`dynamic = 'error'` instead of leaving them under `instant = false`,
which can move rendering to request time and reduce prefetched UI.
- Clarify that existing `fetch` and `unstable_cache` caching can remain
in place during adoption.
- Combine the incremental checkpoint and completion coverage into one
eval that verifies both stages of the migration.
- Make the adoption skill honor an explicit incremental strategy before
continuing through a complete migration.
- Remove the unrelated `.env*` ignore and restore the existing agent-054
eval registration.

## Eval results

`agent-047-adopt-cache-components` runs the complete incremental
migration with `openai/gpt-5.6-luna` through the Codex harness. It
retains the original five checks for the first shippable checkpoint and
the original seven checks for completing the migration.

| Treatment | Result | Notes |
| --- | --- | --- |
| Baseline | 11/12 | Preserved the final behavior, but treated the work
as a fresh migration instead of explicitly continuing from the recorded
first checkpoint. |
| Guide (`AGENTS.md`) | 8/12 | Built successfully, but rewrote the
existing `unstable_cache`, changed the catalog's hourly cadence, moved
its timestamp to request time, and skipped the recorded incremental
checkpoint. |
| Adoption skill | 12/12 | Preserved both cache lifetimes and static
contracts, recorded a passing incremental checkpoint, removed the
remaining opt-outs, and completed the migration. |

## Verification

- `pnpm build`
- Luna eval runs for the baseline, guide, and adoption-skill treatments
- Prettier and ESLint checks for the changed guide, skill, and eval
files
- `git diff --check`

<!-- NEXT_JS_LLM -->
parent be2c3fdb
/** /**
* Adopt Cache Components * Complete an incremental Cache Components migration
* *
* Verifies a complete adoption rather than a single directive. The agent must * Verifies the safe first-PR checkpoint and the completed migration in one
* enable the feature, use targeted caches for reusable data, preserve * agent run.
* request-specific behavior, and create meaningful static shells instead of
* silencing blocking routes with opt-outs.
*/ */
import { expect, test } from 'vitest' import { expect, test } from 'vitest'
...@@ -35,15 +33,51 @@ function readSourceFiles(dir: string): string[] { ...@@ -35,15 +33,51 @@ function readSourceFiles(dir: string): string[] {
const source = readSourceFiles(process.cwd()).join('\n') const source = readSourceFiles(process.cwd()).join('\n')
test('enables Cache Components without route opt-outs', () => { test('enables Cache Components without incompatible segment config', () => {
const config = readFileSync(join(process.cwd(), 'next.config.ts'), 'utf-8')
expect(config).toMatch(/cacheComponents\s*:\s*true/)
expect(source).not.toMatch(
/export\s+(?:const|var|let)\s+(?:dynamic|revalidate|fetchCache)\s*=/
)
})
test('preserves routes that were explicitly static', async () => {
await expect(environment).toSatisfyCriterion(
`Cache Components is enabled. Both routes that began with an explicit static contract are fully migrated in the first PR: the catalog route that used dynamic = 'force-static' remains prerendered and eligible for full-route prefetching, and the privacy route that used dynamic = 'error' remains fully static. Neither route, nor a parent segment covering it, is left under instant = false.`
)
})
test('preserves the catalog route and data cache lifetimes', async () => {
await expect(environment).toSatisfyCriterion(
`The catalog preserves its two independent cache behaviors: the rendered route, including its catalog-check timestamp, can refresh about once per hour, while the product-list lookup can remain cached for about one day. The existing unstable_cache implementation may remain unchanged and is not needlessly migrated merely to enable Cache Components.`
)
})
test('records the first incremental migration PR before continuing', async () => {
await expect(transcript).toSatisfyCriterion(
`Before continuing to the full-app migration, the agent records a shippable first migration PR. The account route's incompatible dynamic = 'force-dynamic' export is removed without adding replacement rendering or caching code solely for that config. Its cookie greeting remains request-specific, and the route may remain under instant = false at this checkpoint. The product route may also remain explicitly opted out, but the explicitly static catalog and privacy routes are not deferred with them. The app builds at this checkpoint before the agent continues.`
)
})
test('prioritizes protected routes and verifies the result', async () => {
await expect(transcript).toSatisfyCriterion(
`Before declaring the first migration PR ready, the agent inventories incompatible route configs. It identifies routes with pre-existing force-static or dynamic-error behavior as high-priority compatibility contracts, completes those static-route migrations rather than leaving them under blanket opt-outs, and verifies them with a successful production build. It may defer the request-specific account and product routes with instant = false for later PRs. Its verification distinguishes preserved route prerendering and navigation prefetch behavior from merely preserving an inner data cache or obtaining a green build through opt-outs.`
)
})
test('completes Cache Components adoption without route opt-outs', () => {
const config = readFileSync(join(process.cwd(), 'next.config.ts'), 'utf-8') const config = readFileSync(join(process.cwd(), 'next.config.ts'), 'utf-8')
expect(config).toMatch(/cacheComponents\s*:\s*true/) expect(config).toMatch(/cacheComponents\s*:\s*true/)
expect(source).not.toMatch(/export\s+(?:const|var|let)\s+instant\s*=\s*false/) expect(source).not.toMatch(/export\s+(?:const|var|let)\s+instant\s*=\s*false/)
expect(source).not.toMatch(/TODO:\s*Cache Components adoption/)
}) })
test('removes incompatible route revalidation config', () => { test('keeps incompatible route segment config removed', () => {
expect(source).not.toMatch(/export\s+(?:const|var|let)\s+revalidate\s*=/) expect(source).not.toMatch(
/export\s+(?:const|var|let)\s+(?:dynamic|revalidate|fetchCache)\s*=/
)
}) })
test('uses explicit cache lifetime for reusable work', () => { test('uses explicit cache lifetime for reusable work', () => {
...@@ -59,7 +93,7 @@ test('preserves request-specific account behavior and a meaningful shell', async ...@@ -59,7 +93,7 @@ test('preserves request-specific account behavior and a meaningful shell', async
test('preserves the catalog cache and timestamp cadence', async () => { test('preserves the catalog cache and timestamp cadence', async () => {
await expect(environment).toSatisfyCriterion( await expect(environment).toSatisfyCriterion(
`The catalog keeps the starter route's hourly revalidation behavior after the incompatible revalidate export is removed. A page-level or data-level use-cache boundary with an equivalent cache lifetime is valid. The catalog check timestamp belongs to that same hourly result and refreshes when the cached result refreshes; it is not incorrectly required to change on every request.` `The catalog keeps its hourly route revalidation behavior and its one-day product-list cache. The catalog check timestamp belongs to the hourly cached result and refreshes when that result refreshes; it is not incorrectly required to change on every request. The existing unstable_cache implementation may remain unchanged.`
) )
}) })
...@@ -69,8 +103,8 @@ test('keeps URL-specific product work below a Suspense boundary', async () => { ...@@ -69,8 +103,8 @@ test('keeps URL-specific product work below a Suspense boundary', async () => {
) )
}) })
test('diagnosed blocking routes and completed the production migration', async () => { test('removes the remaining opt-outs and completes the production migration', async () => {
await expect(transcript).toSatisfyCriterion( await expect(transcript).toSatisfyCriterion(
`The agent enabled cacheComponents, used a production build or Next.js runtime diagnostics to discover the resulting blocking routes, fixed each route according to whether its content was reusable or request-specific, and finished with a successful production build. It did not merely add route-wide opt-outs or stop after the first green type check.` `The agent recognizes that Cache Components is already enabled and continues from the first incremental migration PR. It removes the remaining temporary opt-outs, uses a production build or Next.js runtime diagnostics to discover the account and product blockers, fixes each route according to whether its content is reusable or request-specific, and finishes with a successful production build. It does not stop after merely deleting instant = false or obtaining a green type check.`
) )
}) })
Move this storefront to Cache Components in one branch. The catalog, product pages, account greeting, and timestamps should keep their current behavior. Finish with a production build and do not leave routes opted out. Migrate this storefront to Cache Components incrementally and complete the migration.
import { cookies } from 'next/headers' import { cookies } from 'next/headers'
export const dynamic = 'force-dynamic'
export default async function AccountPage() { export default async function AccountPage() {
const cookieStore = await cookies() const cookieStore = await cookies()
const displayName = cookieStore.get('display-name')?.value ?? 'Guest' const displayName = cookieStore.get('display-name')?.value ?? 'Guest'
......
...@@ -11,7 +11,8 @@ export default function RootLayout({ children }: { children: ReactNode }) { ...@@ -11,7 +11,8 @@ export default function RootLayout({ children }: { children: ReactNode }) {
<html lang="en"> <html lang="en">
<body> <body>
<nav> <nav>
<Link href="/">Catalog</Link> <Link href="/account">Account</Link> <Link href="/">Catalog</Link> <Link href="/privacy">Privacy</Link>{' '}
<Link href="/account">Account</Link>
</nav> </nav>
{children} {children}
</body> </body>
......
import Link from 'next/link' import Link from 'next/link'
import { getProducts } from '@/lib/catalog' import { getProducts } from '@/lib/catalog'
export const dynamic = 'force-static'
export const revalidate = 3600 export const revalidate = 3600
export default async function CatalogPage() { export default async function CatalogPage() {
......
export const dynamic = 'error'
export default function PrivacyPage() {
return (
<main>
<h1>Privacy</h1>
<p>We only use account data to personalize your experience.</p>
</main>
)
}
import { unstable_cache } from 'next/cache'
export type Product = { export type Product = {
slug: string slug: string
name: string name: string
...@@ -17,10 +19,14 @@ const products: Product[] = [ ...@@ -17,10 +19,14 @@ const products: Product[] = [
}, },
] ]
export async function getProducts() { export const getProducts = unstable_cache(
await new Promise((resolve) => setTimeout(resolve, 100)) async () => {
return products await new Promise((resolve) => setTimeout(resolve, 100))
} return products
},
['products'],
{ revalidate: 86400 }
)
export async function getProduct(slug: string) { export async function getProduct(slug: string) {
await new Promise((resolve) => setTimeout(resolve, 100)) await new Promise((resolve) => setTimeout(resolve, 100))
......
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