Next.js prefetch

A <Link> component expresses intent — "prefetch this destination, and how eagerly." But the destination itself has no way to know, ahead of time, which links across your entire app might point at it, or how many of them exist. The prefetch route segment config is where a destination segment sets its own cost ceiling: regardless of what any given link asks for, this is the maximum amount of prefetching work this segment is willing to have done on its behalf, for any visitor who merely has a link to it visible on their screen.

This is another Cache-Components-only option, closely related to (and often used alongside) instant.

Basic Usage

export const prefetch = "partial";

export default function Page() {
  return <div>...</div>;
}

By default, the framework manages prefetch strategy per segment based on your app-wide partialPrefetching config setting — you only need this export at all when you want to override that default for one specific segment.

The Meaningful Values

There are technically three values in the type ('auto' | 'partial' | 'force-disabled'), but only two of them are worth ever writing explicitly:

• 'auto' is the default, and is exactly equivalent to omitting the export entirely — the docs explicitly recommend not writing prefetch = 'auto' yourself, since it does nothing beyond what leaving the export out already does.
• 'partial' and 'force-disabled' are the two values that actually change behavior, and each solves a genuinely different problem.

'partial' — Incremental Adoption of Partial Prefetching

Setting prefetch = 'partial' opts this specific segment into Partial Prefetching without requiring you to flip the global partialPrefetching config flag for your entire application at once. A <Link> pointing at a segment configured this way loads that segment's per-route App Shell, instead of falling back to the legacy full-prefetch behavior.

export const prefetch = "partial";

This is specifically designed as a migration tool: if you can't flip partialPrefetching on globally in one shot — because other parts of your app aren't ready for the behavior change yet — you can adopt it segment by segment, verify each one works correctly, and once every route in scope has been individually opted in, flip the global flag and remove all the now-redundant per-route exports.

What happens for a link explicitly opting into a wider prefetch (<Link prefetch={true}>) pointing at a 'partial' segment: Next.js performs a genuine per-link prefetch, with the server rendering a fresh response that resolves the actual URL-dependent data (params, searchParams, the full URL) rather than just serving the generic App Shell. For fully statically-renderable pages, this per-link prefetch is served straight from the static cache — cheap, fast, no server compute cost per prefetch. For pages that access genuinely non-static data, that data gets prefetched at runtime instead, which does cost real server work per prefetch, not just per eventual page view.

One detail worth knowing if you're building nested routes with mixed configurations: when Next.js performs a per-link prefetch for a segment, all downstream segments are pulled into that same single request — including segments deeper in the tree configured with 'force-disabled'. Setting 'force-disabled' on a child doesn't exempt it from a parent's per-link prefetch response; that config only prevents its own segment-level prefetch requests, not inclusion in a broader response a parent link already triggered.

'force-disabled' — Opting Out Entirely

export const prefetch = "force-disabled";

This tells the client never to request this segment's data ahead of navigation, full stop — regardless of what any pointing <Link> asks for. The stated use case is precise: segments where prefetching would be genuinely wasteful, like a rarely-visited page behind authentication that most visitors will never click through to, where prefetching on every page load that happens to link to it would burn real server work for almost no payoff.

One caveat: 'force-disabled' doesn't prevent Next.js from prefetching route metadata — only the actual segment data (and, per the note above, any deeper segments' data as well) is what gets omitted from prefetching.

The Relationship With <Link prefetch>

It's worth being precise about how these two mechanisms — the <Link> prop and this segment config — actually interact, since they're not competing settings but two ends of the same negotiation:

A prefetch starts with a <Link> expressing intent (should this destination be prefetched, and how eagerly), and ends at a segment that sets a hard ceiling on how much work is acceptable to do on its behalf, ahead of time, for any link pointing there. Because a destination segment structurally can't know in advance which links across the app target it, the segment config is what caps what even the most eager <Link prefetch={true}> is allowed to pull:

• 'partial' — an App Shell for ordinary links; a <Link prefetch={true}> additionally resolves URL-dependent data and cached content.
• 'force-disabled' — segment data is skipped entirely, regardless of link-level intent.

And critically: <Link prefetch={false}> skips prefetching at the link level regardless of how the destination segment is configured — a link explicitly opting out always wins for that specific link, independent of what the destination would otherwise allow.

The cost model worth internalizing: on pages that are fully statically renderable, Next.js serves prefetches from the static cache (or a CDN in front of it) — essentially free, regardless of prefetch volume. But a page that accesses genuinely non-static data (cookies, headers, uncached fetches) gets prefetched at runtime with a fresh server render per prefetch — meaning aggressive prefetching into a dynamic page has a real, recurring server CPU cost per page view across your traffic, not a one-time cost. This is exactly why 'force-disabled' exists as an escape hatch for segments where that recurring cost isn't worth paying.

TypeScript

type Prefetch = "auto" | "partial" | "force-disabled";

export const prefetch: Prefetch = "partial";

Version History

Version	Changes
v16.x.x	prefetch export introduced (Cache Components only)

Key Takeaways

Value	Effect
'auto' (default)	Framework-managed strategy based on the global partialPrefetching setting — don't write this explicitly
'partial'	Opts this segment into Partial Prefetching individually, ahead of a global rollout — the incremental-adoption path
'force-disabled'	Never prefetch this segment's data, regardless of any link's own prefetch intent
<Link prefetch={false}>	Always wins at the link level, overriding whatever the destination segment allows
Static pages	Prefetches served from cache/CDN — effectively free
Dynamic pages	Prefetched at runtime, costing real server CPU per prefetch, not just per view

prefetch exists because prefetching isn't free, and a destination segment is the only place that genuinely understands its own cost — a link author, by contrast, only knows their own intent. Use 'partial' as your incremental-adoption ramp toward the global Partial Prefetching flag, and reserve 'force-disabled' for the specific segments where prefetching would burn real server work for a payoff that essentially never materializes.