cloudflare / cloudflare/vinext

App Router: implement next/cache unstable_navigation()

Open
#3,011 0 comments 0 reactions 0 assignees View on GitHub
nextjs-tracking
Dominant language
TypeScript
Stars
8.8k
Forks
406
Avg merge
2d 6h
Merged PRs (30d)
120

Description

## Next.js Change

**Commits:** [`2cc3694`](https://github.com/vercel/next.js/commit/2cc3694fda396a297d05bf21e46ed970b5396b9a), [`1be0ab8`](https://github.com/vercel/next.js/commit/1be0ab80c4d11bf68b69aa6eb1cd467ecf19e946)
**PRs:** [#97236](https://github.com/vercel/next.js/pull/97236), [#96908](https://github.com/vercel/next.js/pull/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` 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

- vercel/next.js#96908 — upstream implementation
- vercel/next.js#97236 — upstream API scaffold

Contributor guide

Open the contributing guide

Research direction

Start by reading the upstream implementation in commits 2cc3694 and 1be0ab8 and the related PRs #96908 and #97236. Trace vinext's next/cache export and App Router development and production request paths, then verify each acceptance criterion, including static prerenders, runtime shells, prefetches, navigation responses, and server-only import errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, typescript
Domain
api, backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.