Unverified Commit b86f97bb authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: tighten Partial Prefetching API references and adoption guide (#94818)

### What?

Three friction points found while running through the Partial
Prefetching migration on a Cache Components app:

- **`prefetch.mdx`** — added `'partial'`. It's a real value in the
framework but the docs page didn't list it.
- **`link.mdx`** — rewrote the `prefetch={true}` bullet so it's correct
on its own under Partial Prefetching, not only inside the callout below.
- **`adopting-partial-prefetching.mdx`** — restored the "Going further"
section and added a before/after migration example.

### Related

[#94798](https://github.com/vercel/next.js/pull/94798) — Insight surface
for the new `<Link prefetch={true}>` warning. Lands independently.

---------
Co-authored-by: 's avatarJoseph <joseph.chamochumbi@vercel.com>
Co-authored-by: 's avatarJoseph <sephxd1234@gmail.com>
Co-authored-by: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
parent eb9b1dad
......@@ -88,6 +88,34 @@ const nextConfig: NextConfig = {
export default nextConfig
```
## Auditing existing `<Link prefetch={true}>` calls
When `partialPrefetching` is enabled, `<Link prefetch={true}>` now prefetches the App Shell plus cached content, but not dynamic data. Review each existing usage and decide whether the prop is still providing value.
Previously, `<Link prefetch={true}>` also prefetched dynamic data.
| Destination | Recommendation |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Fully static (no `"use cache"`, no Suspense) | Drop `prefetch={true}`. The default `<Link>` already loads the full page because the App Shell is the page. |
| Has cached content worth shipping ahead of the click | Keep `prefetch={true}`. The cached parts come with the App Shell. |
| Reads request data (`cookies()`, `headers()`, `searchParams`) the user will need on arrival | Keep `prefetch={true}` and opt the route into [runtime prefetching](/docs/app/guides/runtime-prefetching) with `prefetch = 'allow-runtime'`. |
Before:
```tsx filename="app/nav.tsx"
<Link href="/about" prefetch={true}>About</Link> {/* static page */}
<Link href="/products" prefetch={true}>Products</Link> {/* cached list */}
<Link href="/dashboard" prefetch={true}>Dashboard</Link> {/* reads cookies */}
```
After:
```tsx filename="app/nav.tsx"
<Link href="/about">About</Link> {/* default is enough */}
<Link href="/products" prefetch={true}>Products</Link> {/* unchanged */}
<Link href="/dashboard" prefetch={true}>Dashboard</Link> {/* and add `prefetch = 'allow-runtime'` to /dashboard */}
```
## Next steps
- [Runtime prefetching](/docs/app/guides/runtime-prefetching) for per-link runtime prefetches and App Shells in depth.
......
......@@ -300,10 +300,10 @@ Prefetching happens when a `<Link />` component enters the user's viewport (init
The following values can be passed to the `prefetch` prop:
- **`"auto"` or `null` (default)**: Prefetch behavior depends on whether the route is static or dynamic. For static routes, the full route will be prefetched (including all its data). For dynamic routes, the partial route down to the nearest segment with a [`loading.js`](/docs/app/api-reference/file-conventions/loading#instant-loading-states) boundary will be prefetched.
- `true`: The full route will be prefetched for both static and dynamic routes.
- **`true`**: The full route is prefetched for both static and dynamic routes. With [Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) enabled, the prefetch is the [App Shell](/docs/app/glossary#app-shell) plus the route's cached content; dynamic data is excluded.
- `false`: Prefetching will never happen both on entering the viewport and on hover.
> **With Partial Prefetching enabled** ([`partialPrefetching: true`](/docs/app/api-reference/config/next-config-js/partialPrefetching)): the default changes. `auto` prefetches only the per-route [App Shell](/docs/app/glossary#app-shell), not the page content. Set `prefetch={true}` to also prefetch the destination page's content. See [Adopting Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) for the full behavior change.
> **With Partial Prefetching enabled** ([`partialPrefetching: true`](/docs/app/api-reference/config/next-config-js/partialPrefetching)): the default changes. `auto` prefetches only the per-route [App Shell](/docs/app/glossary#app-shell), not the page content. See [Adopting Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) for the full behavior change.
```tsx filename="app/page.tsx" switcher
import Link from 'next/link'
......
......@@ -54,6 +54,16 @@ Allows Next.js to prefetch this segment at runtime. Today, setting this option c
export const prefetch = 'allow-runtime'
```
### `'partial'`
Opts the segment into [Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) without enabling the global [`partialPrefetching`](/docs/app/api-reference/config/next-config-js/partialPrefetching) flag. A `<Link>` pointing at a segment with `prefetch = 'partial'` loads the per-route [App Shell](/docs/app/glossary#app-shell) instead of the legacy full prefetch. Set this on the destination, not the link.
Use this for incremental adoption when you can't enable `partialPrefetching` for the entire app at once. Once every route in scope has `prefetch = 'partial'`, enable the global flag and remove the per-route exports.
```tsx filename="page.tsx"
export const prefetch = 'partial'
```
### `'force-static'`
Always prefetch this segment statically, even if it has not been validated with `instant`. Use this when you know the segment produces a valid static shell but do not want to set up instant validation.
......@@ -76,7 +86,12 @@ In general, both of these are special circumstances. The default behavior — wh
## TypeScript
```tsx
type Prefetch = 'auto' | 'force-disabled' | 'force-static' | 'allow-runtime'
type Prefetch =
| 'auto'
| 'allow-runtime'
| 'partial'
| 'force-static'
| 'force-disabled'
export const prefetch: Prefetch = 'allow-runtime'
```
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment