App Router: implement next/cache unstable_prefetch()

[ask-bonk]

Next.js Change

Commits: 55b26f9, 3cdb56c
PRs: #97618, #97622

What changed

Next.js adds unstable_prefetch() to next/cache. App Router Server Components can await it to exclude the following subtree from an App Shell while retaining it in static and speculative prefetches. The boundary resolves during static prerendering and static prefetches, and it also resolves in runtime speculative prefetches (<Link prefetch={true}>) and full navigations.

Unlike unstable_navigation(), it does not stop runtime-data tracking: cookies() or headers() below the boundary still make the route request-dependent. It is unavailable in Client Components and the Pages Router.

Impact on vinext

vinext must expose unstable_prefetch() from next/cache and implement its App Router render-stage behavior in development and production. Without it, applications using this experimental Next.js API cannot import it or control whether server-rendered content belongs in an App Shell versus a full prefetch/navigation response.

Acceptance criteria

• Export unstable_prefetch(): Promise<void> from next/cache for App Router Server Components.
• Reject imports from Client Components and Pages Router modules with a Next-compatible server-only error.
• Resolve content behind the boundary during static prerendering and static prefetches.
• Exclude content behind the boundary from static and runtime App Shells, showing its Suspense fallback until a later response arrives.
• Include the boundary content in runtime speculative prefetches (<Link prefetch={true}>) and full navigations.
• Continue tracking runtime APIs used after the boundary so they still affect route prefetchability.
• Implement and test the behavior in both development and production request paths.

Related

• Support unstable_prefetch route segment config #849 - unstable_prefetch route segment config
• Support partialPrefetching global config and unstable_prefetch = 'partial' segment opt-in #1819 - partialPrefetching config and segment opt-in
• App Router: implement next/cache unstable_navigation() #3011 - unstable_navigation() API
• [PPF] Scaffold unstable_prefetch() vercel/next.js#97618 - upstream API scaffold
• [PPF] unstable_prefetch() vercel/next.js#97622 - upstream implementation