Adopting Partial Prefetching

Partial Prefetching changes what a <Link> downloads for a Cache Components route. With Partial Prefetching enabled, a <Link> prefetches the route's App Shell: its static content and the cached content that doesn't depend on the URL. Next.js builds one App Shell per route and reuses it for every link to that route, rather than prefetching each link separately as it did before.
To prefetch more than the App Shell, a link can opt into per-link prefetching with <Link prefetch={true}>. The prefetch can then resolve cached URL-specific content that depends on params, searchParams, or the full URL.
Along the way, Next.js surfaces instant navigation insights in development, naming the link or route to change.
Partial Prefetching only works when cacheComponents is enabled.
The next-partial-prefetching-adoption skill drives this adoption with a coding agent. It reviews your <Link prefetch={true}> calls, captures the prefetched UI to preserve with instant() tests when a production test rig is available, then enables the flag and checks each route for the insights this guide covers.
Then give the agent this prompt:
To adopt an existing app by hand:
Both insights are development-only and never block the build. They appear in the dev overlay with fix cards that link the docs page for each fix. If a route isn't ready to adopt, export instant = false from its page or layout to opt the route out of instant-navigation validation, and return to it later.
In an existing app, review the UI delivered by <Link prefetch={true}> before enabling Partial Prefetching. These links use the legacy full prefetch, and enabling Partial Prefetching changes their behavior.
Enable partialPrefetching in next.config.ts:
After enabling the flag, links using the default behavior, prefetch="auto", or prefetch={true} prefetch the destination's App Shell. A link with prefetch={true} can also resolve cached URL-specific content, but it no longer includes uncached dynamic content from the legacy full prefetch. New projects can enable the flag without this audit because they have no legacy full prefetches to migrate.
When cacheComponents is enabled without a partialPrefetching value, Next.js logs a warning asking you to set it to true or false. Set false only to keep the previous prefetch behavior while you work through this guide. Both features will be enabled everywhere in the next major release, and the options will be removed.
The App Shell is shared across every link to a given route, regardless of dynamic params, so rendering many <Link>s to the same destination doesn't multiply the work.
Before Partial Prefetching, a <Link> whose effective prefetch value is true prefetches the complete destination, including uncached dynamic content. This includes prefetch={true}, the bare prefetch prop, and wrapper or conditional props that resolve to true. The default value, prefetch="auto", and prefetch={false} don't use the legacy full prefetch.
A legacy full prefetch can include more UI than the navigation needs. In most cases, the primary content at the top of the destination should be available before navigation, while secondary or frequently changing content can stream afterward.
cookies() and headers() don't tie a prefetch to a URL. They vary per session, not per link, so the App Shell still carries session content. Only params and searchParams are URL data, which varies per link and can't be included in the shared App Shell.
To verify the migration programmatically, an instant() test can capture the UI that should stay available from an existing full prefetch. Test the exact source link because different links to the same destination can use different prefetch settings:
Run this baseline against a production build with partialPrefetching disabled because automatic prefetching doesn't run in next dev. Then rerun the same test after adopting the destination. If it fails, the selected UI is no longer prefetched. Cache the reusable data or subtree that should stay available, then keep the passing test as regression coverage.
The output is already in the App Shell. Remove the now-redundant prefetch={true}:
Cache it with use cache so it gets included in the App Shell, then remove prefetch={true} from the links:
The App Shell carries cached content whose stale time is at least 5 minutes, which holds for the default profile used above and every preset except seconds. Shorter-lived content streams in after the navigation instead. See Prerendering behavior.
Content behind cookies() or headers() varies per session, not per link, and session data resolves in the App Shell, so cached session content still gets included. Read the session value outside the cached function and pass it in, then remove prefetch={true} from the links:
URL data (params, searchParams) varies per link, so content that depends on it can't be included in the shared App Shell and streams in after navigation from behind its <Suspense> boundary. The links keep prefetch={true}, and Prefetching URL data covers prefetching the content ahead of the click.
A prefetch of real-time content would be stale by the click, so there is nothing to preserve. Remove prefetch={true} and let the content stream in from behind its <Suspense> boundary.
Adoption doesn't have to happen in one change. prefetch = 'partial' is the global flag scoped to one route, so with the global flag still off, you can adopt and deploy each destination on its own.
Before a destination opts into Partial Prefetching, prefetch={true} performs the legacy full prefetch. Navigating through one of these links in development surfaces the dynamic data during prefetching insight, naming the destination and pointing at its fixes:
Each card is clickable and opens a page with patterns, code samples, and trade-offs.
Start with one destination. Preserve the intended prefetched UI and update its prefetch={true} links using the patterns above. Then add export const prefetch = 'partial' to its page or layout, which clears the insight