cloudflare / cloudflare/vinext

Cache Components: align short-lifetime cache behavior with partial prefetching

Open
#3,199 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:**
- [`e974969`](https://github.com/vercel/next.js/commit/e974969ddd0d4dfe1529ae8ad1159a6f91ef1327) ([#98339](https://github.com/vercel/next.js/pull/98339))
- [`f4449e8`](https://github.com/vercel/next.js/commit/f4449e8fa58d137a82bb3667eedfff80466de3ae) ([#98342](https://github.com/vercel/next.js/pull/98342))
- [`b0b7a42`](https://github.com/vercel/next.js/commit/b0b7a429b931b08eb33b18f5c31caf25864004b0) ([#98278](https://github.com/vercel/next.js/pull/98278))

## What changed

Next.js refined Cache Components behavior when `cacheLife()` has short `stale` or `expire` values:

- `stale < MIN_SHELL_STALE` means a cache is excluded from App Shells but remains eligible for a per-link prefetch. This is prefetch-only data, not runtime data.
- `stale < MIN_PREFETCHABLE_STALE` excludes a cache from all prerenders and prefetches.
- `expire < MIN_PRERENDERABLE_EXPIRE` excludes a cache from static prerenders but permits it in runtime prerenders.
- `unstable_prefetch()` and prefetch-only short-stale caches must not be treated as runtime-data access.
- Instant Validation must apply these rules on both cold and warm caches during development and build-time validation.
- When a revalidated route starts accessing request data, the client segment cache must issue the required runtime follow-up rather than reuse incomplete static content.

## Impact on vinext

vinext implements the Cache Components / `'use cache'` surface and App Router navigation. Its cache metadata and prefetch behavior should not classify prefetch-only cached content as runtime data or serve incomplete cached content after a route changes its dynamic requirements.

## Acceptance criteria

- [ ] Preserve `stale` when reading and writing cache entries.
- [ ] Implement the three upstream cache eligibility boundaries for any supported partial-prefetch/App Shell mode.
- [ ] Ensure `unstable_prefetch()` and shell-excluded short-stale caches do not trigger runtime-data handling.
- [ ] Validate the behavior consistently for cache misses and hits in development and production builds.
- [ ] Ensure a static-to-dynamic revalidation triggers a runtime follow-up before navigation consumes incomplete cached content.
- [ ] Add focused regression coverage for each boundary and the static-to-dynamic revalidation path.

## References

- https://github.com/vercel/next.js/commit/e974969ddd0d4dfe1529ae8ad1159a6f91ef1327
- https://github.com/vercel/next.js/commit/f4449e8fa58d137a82bb3667eedfff80466de3ae
- https://github.com/vercel/next.js/commit/b0b7a429b931b08eb33b18f5c31caf25864004b0

Contributor guide

Open the contributing guide

Research direction

Start by comparing vinext's Cache Components, 'use cache', and App Router prefetch behavior with upstream commits e974969, f4449e8, and b0b7a42. Trace cache metadata through reads and writes and cold/warm validation, then add focused regression coverage for the three boundaries and static-to-dynamic revalidation; done means the acceptance criteria pass in development and production builds.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, typescript
Domain
backend-api-design, performance, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.