cloudflare / cloudflare/vinext

Dev warning: `<Link prefetch={true}>` to non-partial-prefetch route under Cache Components

Open
#1,917 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

**Commit:** [`5c27d82`](https://github.com/vercel/next.js/commit/5c27d82bfb4f0374b00823665bfc55db15d28f8c)
**PR:** [#94672](https://github.com/vercel/next.js/pull/94672)

## What changed

Adds a development-only `console.error` when a client navigation originates from a `` whose target route has **not** opted into Partial Prefetching. In that situation Next.js silently falls back to a legacy full prefetch that includes dynamic data, defeating the static/dynamic split Cache Components provides.

The check fires at **navigation time**, not prefetch time. The rationale:
- In dev, prefetches don't actually run, so the navigation is the only point where both the originating link's `fetchStrategy` and the resolved route tree's `prefetchHints` are in hand.
- Firing at prefetch time would flood an app that just enabled Cache Components with one warning per `` on the page; firing at navigation time means you only hear about a route when you actually navigate there.

The decision reads a single bit (`PrefetchHint.SubtreeHasPartialPrefetching`) at the root of the resolved route tree, which records whether any segment in the route opted into Partial Prefetching.

### Warning text

> A `` navigated to "", but Partial Prefetching is not enabled for that route, so its dynamic data was included in the prefetch. Enable Partial Prefetching app-wide by setting `partialPrefetching: true` in next.config, or per-route by exporting `const prefetch = 'partial'` from the page or layout.

### Known scope limitation

The warning fires on every qualifying navigation, including navigations into fully-static routes where a full prefetch costs nothing. Suppressing it for fully-static targets is deferred upstream because the route-level "has dynamic data" signal isn't cheaply available on cache-served repeat navigations.

### Files changed (non-test)

- `packages/next/src/client/components/segment-cache/navigation.ts` (+31/-0) — adds the warning inside `navigateToKnownRoute`, gated on `process.env.NODE_ENV !== 'production' && process.env.__NEXT_CACHE_COMPONENTS`.

## Impact on vinext

vinext does not yet implement Partial Prefetching or the segment-cache scheduler (tracked in #1614, #1819, #1820). When that work lands, this dev DX warning should be ported alongside it:

1. The warning belongs in the client-side `navigateToKnownRoute` equivalent in vinext's segment-cache navigation path.
2. It must only fire when Cache Components is enabled and the build is in dev (`import.meta.env.DEV` / `process.env.NODE_ENV !== 'production'`).
3. The route tree's `prefetchHints` field must carry the `SubtreeHasPartialPrefetching` bit — same propagation as upstream.
4. The originating ``'s fetch strategy must be available at navigation time (the upstream `getLinkForCurrentNavigation()` plumbing).

Until vinext supports Partial Prefetching, this is a no-op — but worth tracking so the warning isn't forgotten when the rest of the partial-prefetch machinery lands. Users on a vinext app with Cache Components would otherwise silently get the slower full-prefetch behavior with no signal that they should opt into Partial Prefetching.

## Related

- #1820 — `` default behavior change under Partial Prefetching
- #1819 — `partialPrefetching` config + `unstable_prefetch = 'partial'`
- #1614 — Client-side App Shell prefetching (segment cache scheduler)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.