App Router: implement next/cache unstable_navigation()

[ask-bonk]

Next.js Change

Commits: 2cc3694, 1be0ab8
PRs: #97236, #96908

What changed

Next.js adds unstable_navigation() to next/cache. Server Components can await it to defer the following subtree from runtime App Shells and runtime/speculative prefetches, avoiding per-user, per-link work that is only needed during an actual navigation. It does not make the subtree request-dependent.

The boundary resolves during static prerenders, so its content remains in static prefetch output, but it suspends during runtime shells, runtime prefetches, and until the full navigation. It is unavailable in Client Components and in the Pages Router.

Impact on vinext

vinext must expose unstable_navigation() from next/cache and implement the App Router render-stage behavior across development and production. Without it, applications using this experimental Next.js API fail to import or cannot prevent expensive server work from running for runtime shell/prefetch requests.

Acceptance criteria

• Export unstable_navigation(): 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/static prefetches.
• Exclude content behind the boundary from runtime App Shells and runtime/speculative prefetches, rendering its Suspense fallback until the navigation response arrives.
• Keep content behind the boundary cacheable; calling it must not itself make a route request-dependent.
• Implement and test the behavior in both development and production request paths.

Related

• [PPF] unstable_navigation() vercel/next.js#96908 — upstream implementation
• [PPF] Scaffold unstable_navigation() vercel/next.js#97236 — upstream API scaffold