export const prefetch
Caps how much of a route a link preloads before navigation, per segment.
type Prefetch = 'auto' | 'partial' | 'force-disabled'
export const prefetch: Prefetch = 'partial'- Added in Next.js v16.3.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$'auto'optional | string literal= 'auto' | Default. Equivalent to omitting the export — the framework manages the strategy based on the app's partialPrefetching setting. The docs advise against writing it explicitly. |
$'partial'optional | string literal | Opts the segment into Partial Prefetching without enabling the global partialPrefetching flag. A <Link> pointing at the segment loads the per-route App Shell instead of the legacy full prefetch. Set this on the destination, not the link. |
$'force-disabled'optional | string literal | Never prefetch this segment. The client will not request segment data ahead of navigation. Route metadata is still prefetched; segment data for this segment and all deeper segments is omitted. |
Errors
The export cannot be used when the segment is a Client Component, and it is only read when the cacheComponents flag is enabled.
Changelog
- PHP v16.3.0prefetch export introduced (Cache Components only), alongside the partialPrefetching config option. The API reference lists this as v16.x.x.
- PHP v16.3.0The remove-partial-prefetch codemod deletes prefetch = 'partial' exports once partialPrefetching is enabled globally: npx @next/codemod@canary remove-partial-prefetch ./app. It leaves other values such as 'force-disabled' in place.
A prefetch has two ends. The <Link> expresses intent — should this destination be preloaded, and how eagerly. The destination segment sets the cost ceiling — how much work is acceptable ahead of time for any link pointing here. prefetch is that ceiling.
The two values worth writing
'partial'opts one route into Partial Prefetching without flipping the app-widepartialPrefetchingflag. Links to it load the per-route App Shell instead of the legacy full prefetch. This is the incremental adoption path: convert routes one at a time, then enable the global flag and run theremove-partial-prefetchcodemod to delete the per-route exports.'force-disabled'switches segment preloading off — for pages behind authentication that are rarely visited, where the work is usually wasted.
What trips people up
'force-disabled' is not absolute. When Next.js does a per-link prefetch for an ancestor segment, all downstream segments ride along in the same response, so a disabled segment deeper in the tree is still prefetched as part of it. It also does not stop route metadata from being prefetched.
And it goes on the destination, never on the link. A <Link prefetch={false}> skips the work at the link end regardless of how the destination is configured.
Example
export const prefetch = 'partial'
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const res = await fetch(`https://api.example.com/products/${slug}`)
const product: { name: string; price: string } = await res.json()
return (
<article>
<h1>{product.name}</h1>
<p>{product.price}</p>
</article>
)
}When to use it
- Opt one high-traffic product route into Partial Prefetching before enabling partialPrefetching for the whole app.
- Stop preloading a rarely visited billing page that sits behind authentication.
- Cut prefetch traffic on an index page that renders hundreds of links to the same route.
Frequently asked questions
Why is my prefetch route segment config being ignored?
The prefetch export only works when the cacheComponents flag is enabled in next.config, and it cannot be used when the segment is a Client Component.
Should I write export const prefetch = 'auto'?
No — 'auto' is the default and is equivalent to omitting the export; only 'partial' and 'force-disabled' are meaningful to set.
Does prefetch = 'force-disabled' stop all prefetching for that route?
It stops segment data for that segment and everything deeper, but route metadata is still prefetched, and a per-link prefetch of an ancestor segment includes downstream segments in the same response.
More examples
Turning off preloading for an expensive private route
Nothing under /billing is fetched ahead of navigation, including deeper segments. The route's metadata is still prefetched, so this is a data ceiling rather than a complete opt-out of the navigation system.
// app/(account)/billing/page.tsx
import { cookies } from 'next/headers'
export const prefetch = 'force-disabled'
export default async function BillingPage() {
const cookieStore = await cookies()
const session = cookieStore.get('session')?.value
const res = await fetch('https://api.example.com/billing', {
headers: { cookie: `session=${session ?? ''}` },
})
const invoices: { id: string; amount: string }[] = await res.json()
return (
<ul>
{invoices.map((invoice) => (
<li key={invoice.id}>{invoice.amount}</li>
))}
</ul>
)
}Incremental adoption, then the codemod
The documented adoption path. The codemod removes only prefetch = 'partial' and leaves 'force-disabled' exports untouched, so the deliberate opt-outs survive the cleanup.
// Step 1 — next.config.ts: Cache Components on, global flag still off.
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
// Step 2 — opt in one route at a time.
// app/products/[slug]/page.tsx
export const prefetch = 'partial'
// Step 3 — once every route in scope is converted, enable the flag:
// partialPrefetching: true
// and delete the now-redundant exports:
// npx @next/codemod@canary remove-partial-prefetch ./appThe ceiling versus the link's intent
Shows both ends of the negotiation. prefetch={true} asks for more than the App Shell and gets it because the destination allows 'partial'; prefetch={false} opts out at the link regardless of the destination's configuration.
// app/page.tsx
import Link from 'next/link'
export default function HomePage() {
return (
<nav>
{/* Destination sets prefetch = 'partial': this link additionally
resolves URL data (params, searchParams, the full URL). */}
<Link href="/products/boots" prefetch={true}>
Boots
</Link>
{/* Skipped at the link end, whatever the destination says. */}
<Link href="/account/billing" prefetch={false}>
Billing
</Link>
</nav>
)
}
Discussion