Unverified Commit 0553b345 authored by Joseph's avatar Joseph Committed by GitHub

doc: instant navs runtime story (#93204)

- changes getting started -> caching
- new guide for instant navs
- new guide for runtime-prefetching (most pending stuff is here)
- x-refs between docs
- App Shell mentions in other docs (ISR w/ CC)

---------
Co-authored-by: 's avatarAurora Scharff <66901228+aurorascharff@users.noreply.github.com>
Co-authored-by: 's avatarAurora Scharff <aurora.sofie@gmail.com>
parent 23b1977e
---
title: Adopting Partial Prefetching
nav_title: Adopting Partial Prefetching
description: Learn how to enable Partial Prefetching and what changes for `<Link>`.
version: draft
related:
title: Next Steps
description: Learn more about prefetching and instant navigations.
links:
- app/guides/instant-navigation
- app/guides/runtime-prefetching
- app/api-reference/components/link
- app/api-reference/config/next-config-js/partialPrefetching
---
[Partial Prefetching](/docs/app/glossary#partial-prefetching) changes what `<Link>` downloads for a Cache Components route. By default, a `<Link>` loads a per-route [App Shell](/docs/app/glossary#app-shell), and the page's cached content is downloaded only when the link sets `prefetch={true}`. This is the biggest change from the pre-Cache Components behavior, where fully static pages were always prefetched by default.
`<Link prefetch={true}>` also stops prefetching dynamic content. It now only prefetches the cached parts of the page, so the link no longer pulls cookies, headers, or other request-time data ahead of the navigation.
> **Good to know**: Partial Prefetching only works when [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled.
## What changes for `<Link>`
| `<Link>` prop | Before (Cache Components default) | After Partial Prefetching |
| ----------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------- |
| `<Link href="/x">` | Prefetched the cached page render. | Loads the App Shell for `/x`. |
| `<Link href="/x" prefetch>` | Prefetched the cached page render **and** any dynamic content. | Loads the App Shell **and** the cached page content. |
| `<Link href="/x" prefetch={false}>` | Disabled prefetching for this link. | Unchanged. Still disabled. |
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.
## Adopting in a new project
Enable [`partialPrefetching`](/docs/app/api-reference/config/next-config-js/partialPrefetching) in `next.config.ts` alongside Cache Components:
```ts filename="next.config.ts" highlight={5}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig
```
Add `prefetch` to any `<Link>` whose destination's cached content is worth shipping ahead of the navigation. Leave it off for the rest:
```tsx filename="app/page.tsx"
import Link from 'next/link'
export default function Page() {
return (
<nav>
<Link href="/products">Products</Link>
<Link href="/checkout" prefetch>
Checkout
</Link>
</nav>
)
}
```
## Adopting incrementally in an existing project
If you can't enable `partialPrefetching` for the entire app at once, opt routes in one at a time with the [`prefetch`](/docs/app/api-reference/file-conventions/route-segment-config/prefetch) route segment config:
```tsx filename="app/products/[slug]/page.tsx"
export const prefetch = 'partial'
export default function Page() {
return <div>...</div>
}
```
A `<Link>` pointing at a route with `prefetch = 'partial'` loads the App Shell only, even when `partialPrefetching` is not set in `next.config.ts`.
Once every route in scope has `prefetch = 'partial'`, enable the config and remove the per-route exports:
```ts filename="next.config.ts" highlight={5}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig
```
## Next steps
- [Runtime prefetching](/docs/app/guides/runtime-prefetching) for per-link runtime prefetches and App Shells in depth.
- [`partialPrefetching` API reference](/docs/app/api-reference/config/next-config-js/partialPrefetching) for the global config flag.
- [`prefetch` API reference](/docs/app/api-reference/file-conventions/route-segment-config/prefetch) for the per-segment prefetch config.
- [`<Link>` API reference](/docs/app/api-reference/components/link#prefetch) for the per-link `prefetch` prop.
- [Instant navigation](/docs/app/guides/instant-navigation) to validate that the routes you've marked actually navigate instantly.
--- ---
title: Incremental Static Regeneration with Cache Components title: Incremental Static Regeneration with Cache Components
description: Learn how to prerender a subset of dynamic routes, serve fallback shells for the rest, and upgrade them after the first visit. description: Learn how to prerender a subset of dynamic routes, serve App Shells for the rest, and upgrade them after the first visit.
nav_title: ISR with Cache Components nav_title: ISR with Cache Components
version: experimental
related: related:
links: links:
- app/api-reference/config/next-config-js/cacheComponents - app/api-reference/config/next-config-js/cacheComponents
...@@ -11,12 +10,14 @@ related: ...@@ -11,12 +10,14 @@ related:
- app/getting-started/caching - app/getting-started/caching
--- ---
[Incremental Static Regeneration (ISR)](/docs/app/glossary#incremental-static-regeneration-isr) with [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) lets you: [Incremental Static Regeneration (ISR)](/docs/app/glossary#incremental-static-regeneration-isr) with [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) gives every route an instant first visit, even for URLs that weren't included in the build.
- Prerender a subset of your dynamic routes at build time with [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) During build, Partial Prerendering splits each render into two parts:
- For routes not included in that subset, prerender a **fallback shell**: the static UI Next.js can produce by treating params as runtime data
- Serve something instantly for every route: either the prerendered page or the fallback shell - The **App Shell**: the generic, reusable part of the page that doesn't depend on URL data
- Progressively improve what visitors see for a given route as param values become known from real traffic - The rest of the statically renderable content: the param-specific prerenders for the URLs you list in [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params)
For a visit to a URL whose params were included in `generateStaticParams`, Next.js serves the fully prerendered page from the cache. For a visit to a URL whose params weren't, Next.js serves the App Shell instantly, then upgrades it in the background with the now-known params. Subsequent visits to that URL get the upgraded result from the cache, skipping the App Shell entirely.
If you have used [ISR](/docs/app/guides/incremental-static-regeneration) or [`fallback: true`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-true) in the Pages Router, this is the Cache Components equivalent. If you have used [ISR](/docs/app/guides/incremental-static-regeneration) or [`fallback: true`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-true) in the Pages Router, this is the Cache Components equivalent.
...@@ -41,7 +42,7 @@ We'll build a product catalog with category layouts and product detail pages usi ...@@ -41,7 +42,7 @@ We'll build a product catalog with category layouts and product detail pages usi
### Prepare your routes ### Prepare your routes
Use [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) to define which param values to prerender. When rendering these routes, the param values are known at build time. The prerender process builds a static shell until it hits runtime APIs or uncached data. See [how rendering works](/docs/app/getting-started/caching#how-rendering-works) for more details. Use [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) to define which param values to prerender. When rendering these routes, the param values are known at build time. The prerender process builds a static shell until it hits runtime APIs or uncached data. See [Prerendering](/docs/app/getting-started/caching#prerendering) for more details.
The category layout prerenders two categories: The category layout prerenders two categories:
...@@ -82,7 +83,7 @@ export default function CategoryLayout(props: LayoutProps<'/[category]'>) { ...@@ -82,7 +83,7 @@ export default function CategoryLayout(props: LayoutProps<'/[category]'>) {
} }
``` ```
Notice that `CategoryLayout` does not `await props.params` itself. Instead, it passes the `params` promise to `CategoryHeader` inside `<Suspense>`. The `await` happens inside the boundary, so for unknown categories Next.js can still generate a static shell with the fallback UI. Notice that `CategoryLayout` does not `await props.params` itself. Instead, it passes the `params` promise to `CategoryHeader` inside `<Suspense>`. The `await` happens inside the boundary, so for unknown categories Next.js can still generate the App Shell.
The product page prerenders one product per category. `generateStaticParams` receives the parent `category` param: The product page prerenders one product per category. `generateStaticParams` receives the parent `category` param:
...@@ -167,9 +168,9 @@ If your components access runtime APIs like `cookies` or `headers`, wrap them in ...@@ -167,9 +168,9 @@ If your components access runtime APIs like `cookies` or `headers`, wrap them in
### At build time ### At build time
When you run `next build`, Next.js prerenders the layout for each known category (`tops`, `shorts`), plus one render where `await params` suspends, producing the `[category]` shell. When you run `next build`, Next.js prerenders the layout for each known category (`tops`, `shorts`), plus one render where `await params` suspends, producing the App Shell for `[category]`.
It also prerenders the page for each known product under each category (`tee` under `tops`, `joggers` under `shorts`), plus one render where `await params` suspends, producing the `[product]` shell. It also prerenders the page for each known product under each category (`tee` under `tops`, `joggers` under `shorts`), plus one render where `await params` suspends, producing the App Shell for `[product]`.
These are combined into: These are combined into:
...@@ -181,21 +182,21 @@ These are combined into: ...@@ -181,21 +182,21 @@ These are combined into:
A visitor navigates to `/tops/tee`. Both params were prerendered. They get a fully static page. A visitor navigates to `/tops/tee`. Both params were prerendered. They get a fully static page.
The first visit to `/tops/overshirt`. The product is unknown, but the category `tops` was prerendered. Next.js serves the `/tops/[product]` shell with the category header already rendered. The product streams in. The first visit to `/tops/overshirt`. The product `overshirt` is unknown, but the category `tops` was prerendered. Next.js serves the App Shell for `/tops/[product]` with the category header already rendered. The product streams in.
The first visit to `/shoes/basketball-shoes`. The category `shoes` was not prerendered. Next.js serves the generic `/[category]/[product]` shell. Both the category and the product stream in. The first visit to `/shoes/basketball-shoes`. Neither param was prerendered. Next.js serves the generic App Shell for `/[category]/[product]`. Both the category and the product stream in.
After the first visit, Next.js renders these routes in the background with the now-known params. The next visitor to the same URLs gets a more specific result. After the first visit, Next.js renders these routes in the background with the now-known params. The next visitor to the same URLs gets the upgraded result.
### What the upgrade produces ### What the upgrade produces
After the first visit, Next.js renders the page in the background with the known params and tries to push the static boundary as far down the component tree as possible: After the first visit, Next.js renders the page in the background with the known params and tries to push the static boundary as far down the component tree as possible:
- If every data access is cached and all params are resolved, the upgrade produces a **fully static page**. - If every data access is cached and all params are resolved, the upgrade produces a **fully static page**.
- If some data is uncached or runtime APIs (`cookies`, `headers`) are accessed behind `<Suspense>` fallbacks, the upgrade produces a **more specific shell** with the params resolved but the dynamic parts still streaming. - If all params are resolved but the render still hits uncached data or runtime APIs (`cookies`, `headers`) wrapped in `<Suspense>` boundaries, the upgrade produces a **cached page with those fallbacks**. The uncached or runtime parts stream in at request time.
- Params are resolved in route order. A param without `generateStaticParams` blocks all subsequent params from upgrading. - Params are resolved in route order. A param value not returned by `generateStaticParams` stays unresolved and prevents any deeper params from upgrading.
> **Good to know**: Prefetching also triggers upgrades. When a [`<Link>`](/docs/app/api-reference/components/link) enters the viewport or [`router.prefetch`](/docs/app/api-reference/functions/use-router) is called, Next.js can upgrade the shell in the background, so the next visitor gets the more specific version even before anyone actually navigates to the page. > **Good to know**: Prefetching also triggers upgrades. When a [`<Link>`](/docs/app/api-reference/components/link) enters the viewport or [`router.prefetch`](/docs/app/api-reference/functions/use-router) is called, Next.js can upgrade the App Shell in the background, so the next visitor gets the more specific version even before anyone actually navigates to the page.
## Coming from the Pages Router ## Coming from the Pages Router
...@@ -210,6 +211,6 @@ If you are migrating from the Pages Router: ...@@ -210,6 +211,6 @@ If you are migrating from the Pages Router:
- [Caching with Cache Components](/docs/app/getting-started/caching) for the full caching model - [Caching with Cache Components](/docs/app/getting-started/caching) for the full caching model
- [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) for controlling which param combinations are prerendered - [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) for controlling which param combinations are prerendered
- [`loading.tsx`](/docs/app/api-reference/file-conventions/loading) for providing skeleton UI in fallback shells - [`loading.tsx`](/docs/app/api-reference/file-conventions/loading) for providing skeleton UI in App Shells
- [Streaming](/docs/app/guides/streaming) to learn how to progressively render UI as data becomes available - [Streaming](/docs/app/guides/streaming) to learn how to progressively render UI as data becomes available
- [Self-hosting](/docs/app/guides/self-hosting#caching-and-isr) to keep an existing ISR [`cacheHandler`](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath) alongside [`cacheHandlers`](/docs/app/api-reference/config/next-config-js/cacheHandlers) for `'use cache'` - [Self-hosting](/docs/app/guides/self-hosting#caching-and-isr) to keep an existing ISR [`cacheHandler`](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath) alongside [`cacheHandlers`](/docs/app/api-reference/config/next-config-js/cacheHandlers) for `'use cache'`
...@@ -13,6 +13,8 @@ This guide will explain how prefetching works and show common implementation pat ...@@ -13,6 +13,8 @@ This guide will explain how prefetching works and show common implementation pat
- [Extending or ejecting link](#extending-or-ejecting-link) - [Extending or ejecting link](#extending-or-ejecting-link)
- [Disabled prefetch](#disabled-prefetch) - [Disabled prefetch](#disabled-prefetch)
> **Using Cache Components?** With [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, `<Link>` defaults to prefetching a per-route [App Shell](/docs/app/glossary#app-shell) rather than the full page. Set `prefetch={true}` on a `<Link>` to also prefetch the destination page's content. See [Adopting Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) for the behavior change and the recommended adoption path.
## How does prefetching work? ## How does prefetching work?
When navigating between routes, the browser requests assets for the page like HTML and JavaScript files. Prefetching is the process of fetching these resources _ahead_ of time, before you navigate to a new route. When navigating between routes, the browser requests assets for the page like HTML and JavaScript files. Prefetching is the process of fetching these resources _ahead_ of time, before you navigate to a new route.
......
...@@ -102,7 +102,7 @@ However, if this component is rendered at request time, fetching its data will d ...@@ -102,7 +102,7 @@ However, if this component is rendered at request time, fetching its data will d
Even though the header is rendered instantly, it can't be sent to the browser until the product list has finished fetching. Even though the header is rendered instantly, it can't be sent to the browser until the product list has finished fetching.
To protect us from this performance cliff, the first time we **await** this uncached data Next.js shows a [warning](/docs/messages/blocking-route): accessing uncached data outside of `<Suspense>` prevents the route from being prerendered. To protect us from this performance cliff, the first time we **await** this uncached data Next.js shows a [warning](/docs/messages/blocking-prerender-dynamic): accessing uncached data outside of `<Suspense>` prevents the route from being prerendered.
At this point, we have to decide how to **unblock** the response. Either: At this point, we have to decide how to **unblock** the response. Either:
......
This diff is collapsed.
...@@ -377,7 +377,7 @@ This keeps `ProductGrid` simple (it takes a `string`, not a `Promise`) while sti ...@@ -377,7 +377,7 @@ This keeps `ProductGrid` simple (it takes a `string`, not a `Promise`) while sti
| **Navigation** | Prefetched as instant fallback | Not prefetched by default | | **Navigation** | Prefetched as instant fallback | Not prefetched by default |
| **Best for** | Pages where nothing renders without data | Most pages, for granular control | | **Best for** | Pages where nothing renders without data | Most pages, for granular control |
Prefer explicit `<Suspense>` boundaries close to the dynamic access. When the prerenderer encounters dynamic work, it walks up the tree looking for the nearest Suspense boundary. If none is found, the build fails with a [blocking route error](/docs/messages/blocking-route). A `loading.js` high in the tree is a valid boundary, so the framework finds it and stops, but now the entire page falls back to a full-page skeleton instead of streaming granularly. Prefer explicit `<Suspense>` boundaries close to the dynamic access. When the prerenderer encounters dynamic work, it walks up the tree looking for the nearest Suspense boundary. If none is found, the build fails with a [blocking route error](/docs/messages/blocking-prerender-dynamic). A `loading.js` high in the tree is a valid boundary, so the framework finds it and stops, but now the entire page falls back to a full-page skeleton instead of streaming granularly.
### Error handling mid-stream ### Error handling mid-stream
......
--- ---
title: 'use cache: private' title: 'use cache: private'
description: 'Learn how to use the "use cache: private" directive to cache functions that access runtime request APIs.' description: 'Learn how to use the "use cache: private" directive to cache functions that access runtime request APIs.'
version: experimental
related: related:
title: Related title: Related
description: View related API references. description: View related API references.
...@@ -19,14 +18,12 @@ Reach for `'use cache: private'` when: ...@@ -19,14 +18,12 @@ Reach for `'use cache: private'` when:
- You want to cache a function that already accesses runtime data, and refactoring to [move the runtime access outside and pass values as arguments](/docs/app/getting-started/caching#working-with-runtime-apis) is not practical. - You want to cache a function that already accesses runtime data, and refactoring to [move the runtime access outside and pass values as arguments](/docs/app/getting-started/caching#working-with-runtime-apis) is not practical.
- Compliance requirements prevent storing certain data on the server, even temporarily - Compliance requirements prevent storing certain data on the server, even temporarily
Because this directive accesses runtime data, the function executes on every server render and is excluded from running during [static shell](/docs/app/getting-started/caching#how-rendering-works) generation. Because this directive accesses runtime data, the function executes on every server render and is excluded from running during [static shell](/docs/app/getting-started/caching#prerendering) generation.
It is **not** possible to configure custom cache handlers for `'use cache: private'`. It is **not** possible to configure custom cache handlers for `'use cache: private'`.
For a comparison of the different cache directives, see [How `use cache: remote` differs from `use cache` and `use cache: private`](/docs/app/api-reference/directives/use-cache-remote#how-use-cache-remote-differs-from-use-cache-and-use-cache-private). For a comparison of the different cache directives, see [How `use cache: remote` differs from `use cache` and `use cache: private`](/docs/app/api-reference/directives/use-cache-remote#how-use-cache-remote-differs-from-use-cache-and-use-cache-private).
> **Good to know**: This directive is marked as `experimental` because it depends on runtime prefetching, which is not yet stable. Runtime prefetching is an upcoming feature that will let the router prefetch past the [static shell](/docs/app/getting-started/caching#how-rendering-works) into **any** cached scope, not just private caches.
## Usage ## Usage
To use `'use cache: private'`, enable the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) flag in your `next.config.ts` file: To use `'use cache: private'`, enable the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) flag in your `next.config.ts` file:
......
...@@ -303,6 +303,8 @@ The following values can be passed to the `prefetch` prop: ...@@ -303,6 +303,8 @@ The following values can be passed to the `prefetch` prop:
- `true`: The full route will be prefetched for both static and dynamic routes. - `true`: The full route will be prefetched for both static and dynamic routes.
- `false`: Prefetching will never happen both on entering the viewport and on hover. - `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.
```tsx filename="app/page.tsx" switcher ```tsx filename="app/page.tsx" switcher
import Link from 'next/link' import Link from 'next/link'
......
...@@ -96,7 +96,7 @@ Each error identifies the component that would block navigation. The fix is usua ...@@ -96,7 +96,7 @@ Each error identifies the component that would block navigation. The fix is usua
## Configuring validation defaults ## Configuring validation defaults
By default, only segments that explicitly export `instant` are validated. The `experimental.instantInsights.validationLevel` config opts every Page and Default segment into validation at once, without needing to repeat `instant` on each route. By default (`validationLevel: 'warning'`), Cache Components apps validate every Page and Default segment in development. The `experimental.instantInsights.validationLevel` config tunes this behavior — for example, to limit validation to segments that opt in explicitly via `instant`.
```js filename="next.config.js" ```js filename="next.config.js"
module.exports = { module.exports = {
...@@ -110,8 +110,8 @@ module.exports = { ...@@ -110,8 +110,8 @@ module.exports = {
The supported levels are: The supported levels are:
- **`'manual-warning'`** _(framework default)_: Only segments with an explicit `instant` are validated, at warning level (dev only). - **`'warning'`** _(framework default)_: Every Page and Default segment is implicitly validated at warning level (dev only).
- **`'warning'`**: Every Page and Default segment is implicitly validated at warning level (dev only). - **`'manual-warning'`**: Only segments with an explicit `instant` are validated, at warning level (dev only).
Setting `instant = false` on a segment opts it out of validation entirely. Setting `instant = false` on a segment opts it out of validation entirely.
......
--- ---
title: prefetch title: prefetch
description: API reference for the prefetch route segment config. description: API reference for the prefetch route segment config.
version: draft
related: related:
title: Next Steps title: Next Steps
description: Learn how to use instant navigations in practice. description: Learn how to use instant navigations in practice.
......
...@@ -162,7 +162,10 @@ The sections below demonstrate both patterns. ...@@ -162,7 +162,10 @@ The sections below demonstrate both patterns.
All params are runtime data. Param access must be wrapped by Suspense fallback UI. Next.js generates a static shell at build time, and content loads on each request. All params are runtime data. Param access must be wrapped by Suspense fallback UI. Next.js generates a static shell at build time, and content loads on each request.
> **Good to know**: You can also use [`loading.tsx`](/docs/app/api-reference/file-conventions/loading) for page-level fallback UI. > **Good to know**:
>
> - You can also use [`loading.tsx`](/docs/app/api-reference/file-conventions/loading) for page-level fallback UI.
> - In layouts, avoid awaiting `params` at the top level. Doing so prevents the layout from being prerendered. Instead, pass the params promise down to the component that needs it and await there. See [Maximizing the static shell](/docs/app/getting-started/caching#maximizing-the-static-shell) for examples.
```tsx filename="app/blog/[slug]/page.tsx" ```tsx filename="app/blog/[slug]/page.tsx"
import { Suspense } from 'react' import { Suspense } from 'react'
......
...@@ -117,6 +117,7 @@ export default function Page({ searchParams }) { ...@@ -117,6 +117,7 @@ export default function Page({ searchParams }) {
- Since the `searchParams` prop is a promise. You must use `async/await` or React's [`use`](https://react.dev/reference/react/use) function to access the values. - Since the `searchParams` prop is a promise. You must use `async/await` or React's [`use`](https://react.dev/reference/react/use) function to access the values.
- In version 14 and earlier, `searchParams` was a synchronous prop. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future. - In version 14 and earlier, `searchParams` was a synchronous prop. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future.
- `searchParams` is a **[Request-time API](/docs/app/glossary#request-time-apis)** whose values cannot be known ahead of time. Using it will opt the page into **[dynamic rendering](/docs/app/glossary#dynamic-rendering)** at request time. - `searchParams` is a **[Request-time API](/docs/app/glossary#request-time-apis)** whose values cannot be known ahead of time. Using it will opt the page into **[dynamic rendering](/docs/app/glossary#dynamic-rendering)** at request time.
- With [Cache Components](/docs/app/getting-started/caching), where you access `searchParams` in the component tree determines how much of the page can be prerendered. See [Maximizing the static shell](/docs/app/getting-started/caching#maximizing-the-static-shell).
- `searchParams` is a plain JavaScript object, not a `URLSearchParams` instance. - `searchParams` is a plain JavaScript object, not a `URLSearchParams` instance.
### Page Props Helper ### Page Props Helper
......
...@@ -67,7 +67,7 @@ To learn more about these options, see the [MDN docs](https://developer.mozilla. ...@@ -67,7 +67,7 @@ To learn more about these options, see the [MDN docs](https://developer.mozilla.
- `cookies` is an **asynchronous** function that returns a promise. You must use `async/await` or React's [`use`](https://react.dev/reference/react/use) function to access cookies. - `cookies` is an **asynchronous** function that returns a promise. You must use `async/await` or React's [`use`](https://react.dev/reference/react/use) function to access cookies.
- In version 14 and earlier, `cookies` was a synchronous function. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future. - In version 14 and earlier, `cookies` was a synchronous function. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future.
- `cookies` is a [Request-time API](/docs/app/glossary#request-time-apis) whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into [dynamic rendering](/docs/app/glossary#dynamic-rendering). - `cookies` is a [Request-time API](/docs/app/glossary#request-time-apis) whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into [dynamic rendering](/docs/app/glossary#dynamic-rendering).
- With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), calling `cookies()` outside of a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary prevents the route from being prerendered. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime) for fix options. - With [Cache Components](/docs/app/getting-started/caching), calling `cookies()` outside of a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary prevents the route from being prerendered. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime) for fix options.
- The `.delete` method can only be called: - The `.delete` method can only be called:
- In a [Server Function](/docs/app/getting-started/mutating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route). - In a [Server Function](/docs/app/getting-started/mutating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route).
- If it belongs to the same domain from which `.set` is called. For wildcard domains, the specific subdomain must be an exact match. Additionally, the code must be executed on the same protocol (HTTP or HTTPS) as the cookie you want to delete. - If it belongs to the same domain from which `.set` is called. For wildcard domains, the specific subdomain must be an exact match. Additionally, the code must be executed on the same protocol (HTTP or HTTPS) as the cookie you want to delete.
......
...@@ -311,7 +311,7 @@ When using [Cache Components](/docs/app/getting-started/caching) with dynamic ro ...@@ -311,7 +311,7 @@ When using [Cache Components](/docs/app/getting-started/caching) with dynamic ro
> **Good to know**: If you don't know the actual param values at build time, you can return a placeholder param (e.g., `[{ slug: '__placeholder__' }]`) for validation, then handle it in your page with `notFound()`. However, this prevents build time validation from working effectively and may cause runtime errors. > **Good to know**: If you don't know the actual param values at build time, you can return a placeholder param (e.g., `[{ slug: '__placeholder__' }]`) for validation, then handle it in your page with `notFound()`. However, this prevents build time validation from working effectively and may cause runtime errors.
See the [dynamic routes section](/docs/app/api-reference/file-conventions/dynamic-routes#with-cache-components) for detailed walkthroughs, or [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) for prerendering a subset of routes and serving fallback shells for the rest. See the [dynamic routes section](/docs/app/api-reference/file-conventions/dynamic-routes#with-cache-components) for detailed walkthroughs, or [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) for prerendering a subset of routes and serving App Shells for the rest.
### With Route Handlers ### With Route Handlers
......
...@@ -46,7 +46,7 @@ export default async function Page() { ...@@ -46,7 +46,7 @@ export default async function Page() {
- In version 14 and earlier, `headers` was a synchronous function. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future. - In version 14 and earlier, `headers` was a synchronous function. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future.
- Since `headers` is read-only, you cannot `set` or `delete` the outgoing request headers. - Since `headers` is read-only, you cannot `set` or `delete` the outgoing request headers.
- `headers` is a [Request-time API](/docs/app/glossary#request-time-apis) whose returned values cannot be known ahead of time. Using it in will opt a route into **[dynamic rendering](/docs/app/glossary#dynamic-rendering)**. - `headers` is a [Request-time API](/docs/app/glossary#request-time-apis) whose returned values cannot be known ahead of time. Using it in will opt a route into **[dynamic rendering](/docs/app/glossary#dynamic-rendering)**.
- With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), calling `headers()` outside of a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary prevents the route from being prerendered. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime) for fix options. - With [Cache Components](/docs/app/getting-started/caching), calling `headers()` outside of a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary prevents the route from being prerendered. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime) for fix options.
## Examples ## Examples
......
...@@ -35,7 +35,7 @@ When `cacheComponents` is enabled, you can use the following cache functions and ...@@ -35,7 +35,7 @@ When `cacheComponents` is enabled, you can use the following cache functions and
Additionally, `cacheComponents` implements **[Partial Prerendering (PPR)](/docs/app/glossary#partial-prerendering-ppr)** as the default behavior in the App Router. This means the `experimental.ppr` configuration flag and the `experimental_ppr` route segment configuration are no longer necessary and have been removed. Additionally, `cacheComponents` implements **[Partial Prerendering (PPR)](/docs/app/glossary#partial-prerendering-ppr)** as the default behavior in the App Router. This means the `experimental.ppr` configuration flag and the `experimental_ppr` route segment configuration are no longer necessary and have been removed.
Read [How rendering works](/docs/app/getting-started/caching#how-rendering-works) for how the static shell and streaming fit together. Read [Prerendering](/docs/app/getting-started/caching#prerendering) for how the static shell and streaming fit together.
> **Good to know**: If you used experimental PPR in Next.js 15, refer to the [Partial Prerendering (PPR)](/docs/app/guides/upgrading/version-16#partial-prerendering-ppr) section of the Version 16 upgrade guide when migrating. > **Good to know**: If you used experimental PPR in Next.js 15, refer to the [Partial Prerendering (PPR)](/docs/app/guides/upgrading/version-16#partial-prerendering-ppr) section of the Version 16 upgrade guide when migrating.
......
---
title: partialPrefetching
description: Configure the default link prefetch behavior to fetch only the static parts of each route.
related:
title: Related
description: View related API references and guides.
links:
- app/api-reference/config/next-config-js/cacheComponents
- app/api-reference/file-conventions/route-segment-config/prefetch
- app/api-reference/components/link
- app/guides/runtime-prefetching
---
`partialPrefetching` enables Partial Prefetching at the app level. The framework prefetches the static parts of each route by default; opt individual routes into [runtime prefetching](/docs/app/guides/runtime-prefetching) to fetch more.
## Usage
```ts filename="next.config.ts" highlight={5} switcher
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig
```
```js filename="next.config.js" highlight={3} switcher
module.exports = {
cacheComponents: true,
partialPrefetching: true,
}
```
`partialPrefetching` requires [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents). Without it, `next dev` and `next build` throw at config validation.
## Reference
| Value | Description |
| ------- | ------------------------------------------- |
| `true` | Enables Partial Prefetching across the app. |
| `false` | Default. No change to prefetch behavior. |
## How prefetches resolve
With `partialPrefetching` enabled:
- **Plain `<Link>`** prefetches the route's [App Shell](/docs/app/glossary#app-shell), shared across every link to the route.
- **`<Link prefetch={true}>`** prefetches the route's static shell with its cached content.
- **`<Link prefetch={true}>` + per-segment `prefetch = 'allow-runtime'`** prefetches a [runtime prerender](/docs/app/guides/runtime-prefetching) that includes cached content gated by runtime data.
See the [runtime prefetching guide](/docs/app/guides/runtime-prefetching) for the per-link behavior in detail.
## Per-segment overrides
A segment that exports an explicit [`prefetch`](/docs/app/api-reference/file-conventions/route-segment-config/prefetch) value overrides the app-level default for that route.
## Version History
| Version | Change |
| ------- | -------------------------------------------------------------------------- |
| 16.3.0 | `partialPrefetching` introduced. Requires `cacheComponents` to be enabled. |
...@@ -10,6 +10,10 @@ description: A glossary of common terms used in Next.js. ...@@ -10,6 +10,10 @@ description: A glossary of common terms used in Next.js.
The Next.js router introduced in version 13, built on top of React Server Components. It uses file-system based routing and supports layouts, nested routing, loading states, error handling, and more. Learn more in the [App Router documentation](/docs/app). The Next.js router introduced in version 13, built on top of React Server Components. It uses file-system based routing and supports layouts, nested routing, loading states, error handling, and more. Learn more in the [App Router documentation](/docs/app).
## App Shell
A per-route prerender containing only the generic, reusable parts of a page: what Next.js can produce without any URL-specific data. Used as the loading state of last resort by [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) and [runtime prefetching](/docs/app/guides/runtime-prefetching).
# B # B
## Build time ## Build time
...@@ -156,6 +160,10 @@ UI that is unique to a route. Defined by exporting a React component from a [`pa ...@@ -156,6 +160,10 @@ UI that is unique to a route. Defined by exporting a React component from a [`pa
A pattern that allows simultaneously or conditionally rendering multiple pages within the same layout. Created using named slots with the `@folder` convention, useful for dashboards, modals, and complex layouts. Learn more in [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes). A pattern that allows simultaneously or conditionally rendering multiple pages within the same layout. Created using named slots with the `@folder` convention, useful for dashboards, modals, and complex layouts. Learn more in [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes).
## Partial Prefetching
A prefetching strategy for [Cache Components](#cache-components) routes where `<Link>` loads only a per-route [App Shell](#app-shell) by default. The page's cached content is downloaded only when the link sets `prefetch={true}`, and dynamic content is never prefetched. Enable with [`partialPrefetching: true`](/docs/app/api-reference/config/next-config-js/partialPrefetching) in `next.config.ts`. Learn more in the [Adopting Partial Prefetching guide](/docs/app/guides/adopting-partial-prefetching).
## Partial Prerendering (PPR) ## Partial Prerendering (PPR)
A rendering optimization that combines prerendering and dynamic rendering in a single route. The static shell is served immediately while dynamic content streams in when ready, providing the best of both rendering strategies. Learn more in [Cache Components](/docs/app/getting-started/caching). A rendering optimization that combines prerendering and dynamic rendering in a single route. The static shell is served immediately while dynamic content streams in when ready, providing the best of both rendering strategies. Learn more in [Cache Components](/docs/app/getting-started/caching).
......
...@@ -19,5 +19,5 @@ To resolve this issue, you have two main options: ...@@ -19,5 +19,5 @@ To resolve this issue, you have two main options:
## Useful Links ## Useful Links
- [Prerendering and Dynamic Rendering](/docs/app/getting-started/caching#how-rendering-works) - Learn more about the differences between prerendering and dynamic rendering in Next.js. - [Prerendering](/docs/app/getting-started/caching#prerendering) - Learn more about how the static shell and streaming fit together in Next.js.
- [Request-time APIs](/docs/app/glossary#request-time-apis) - Understand more about the usage of dynamic server functions in your Next.js application. - [Request-time APIs](/docs/app/glossary#request-time-apis) - Understand more about the usage of dynamic server functions in your Next.js application.
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