cloudflare / cloudflare/vinext
App Router: implement next/cache unstable_navigation()
- 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
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