cloudflare / cloudflare/vinext

App Router: implement next/cache unstable_prefetch()

Open
#3,058 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:** [`55b26f9`](https://github.com/vercel/next.js/commit/55b26f96ab1d99eb7b8c2c334833cc327376334e), [`3cdb56c`](https://github.com/vercel/next.js/commit/3cdb56c2516c9e3097212b7d84bbacf3d397c67b)
**PRs:** [#97618](https://github.com/vercel/next.js/pull/97618), [#97622](https://github.com/vercel/next.js/pull/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 (``) 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` 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 (``) 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

- #849 - `unstable_prefetch` route segment config
- #1819 - `partialPrefetching` config and segment opt-in
- #3011 - `unstable_navigation()` API
- vercel/next.js#97618 - upstream API scaffold
- vercel/next.js#97622 - upstream implementation

Contributor guide

Open the contributing guide

Research direction

Start by reviewing upstream PRs #97618 and #97622, then inspect vinext's next/cache implementation and App Router render paths. Use related issues #3011, #1819, and #849 to understand existing behavior. Done means all listed acceptance criteria pass in development and production, including server-only errors, shell exclusion, prefetch behavior, and runtime API tracking.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, typescript
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.