next-cache-components-optimizer

Write a failing @next/playwright instant() test that asserts the route's static shell commits under the navigation lock, then push each Suspense boundary down to the specific dynamic read it guards. The route is done when the locked test passes green on a production build and a revert differential confirms the test measures the fix.

Identify the blocking read with next build --debug-prerender, which prints an insight link per blocker. Common fixes include moving top-level awaits into Suspense-wrapped children, starting cookies() reads without awaiting, caching stable data with 'use cache', and deferring auth gates behind a boundary.

Next.js 16.3 or later with cacheComponents: true in next.config.ts is required, plus @next/playwright on the same release line as next. The production build must also enable experimental.exposeTestingApiInProductionBuild, otherwise instant() silently no-ops and tests pass vacuously.

A green instant() test is meaningless if the build lacks the testing API, since the lock never engages and the test passes vacuously. Use the self-validating variant that also asserts deferred content is gated under the lock, and confirm exposeTestingApiInProductionBuild was set at build time.

No, next dev does not prefetch and its lock is unreliable for blocking routes, so dev-mode instant() results are not valid RED or GREEN verdicts. Always measure on a production build served by next start or an equivalent deployed artifact.

Use per-link prefetching only when the whole route depends on URL data like params or searchParams that cannot move behind a boundary. It requires Partial Prefetching adoption, a Link with prefetch={true}, and URL-dependent content behind 'use cache'; otherwise prefer the cheaper static shell approach.