Unverified Commit 901cb556 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: add migration note for experimental cache flags to cacheComponents (#92318)

### What?

Add a "Migrating from experimental flags" section to the
`cacheComponents` config reference page, documenting that
`experimental.useCache` and `experimental.cacheComponents` are
deprecated in favor of top-level `cacheComponents: true`.

### Why?

Three config paths exist with overlapping semantics
(`experimental.useCache`, `experimental.cacheComponents`,
`cacheComponents`), but no documentation explains their relationship or
how to migrate. The build output shows different labels for each
("Experiments: ✓ useCache" vs "Cache Components enabled"), making them
look like different features. Both human developers and AI agents
encounter this ambiguity and may use the wrong flag.

### How?

Added a before/after code example to
`docs/01-app/03-api-reference/05-config/01-next-config-js/cacheComponents.mdx`
showing the migration from either experimental flag to the top-level
config, with a note that both experimental flags are deprecated.

---------
Co-authored-by: 's avatarJoseph <joseph.chamochumbi@vercel.com>
parent f4b40dcd
......@@ -1208,14 +1208,21 @@ The following options have been removed from [`devIndicators`](/docs/app/api-ref
The indicator itself remains available.
### `experimental.dynamicIO`
### `experimental.dynamicIO` and `experimental.useCache`
The `experimental.dynamicIO` flag has been renamed to `cacheComponents`:
The `experimental.dynamicIO` and `experimental.useCache` flags are deprecated. Use top-level [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) instead.
Update your Next config file, by removing the `dynamicIO` flag.
```js filename="next.config.js"
// Before: experimental.useCache
module.exports = {
experimental: {
useCache: true,
},
}
```
```js filename="next.config.js"
// Next.js 15 - experimental.dynamicIO is now removed
// Before: experimental.dynamicIO
module.exports = {
experimental: {
dynamicIO: true,
......@@ -1223,15 +1230,26 @@ module.exports = {
}
```
Add the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) flag set to true.
```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'
```js filename="next.config.js"
// Next.js 16 - use cacheComponents instead
// After
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
```
```js filename="next.config.js" switcher
// After
module.exports = {
cacheComponents: true,
}
```
For more on Cache Components, see [Migrating to Cache Components](/docs/app/guides/migrating-to-cache-components).
### `unstable_rootParams`
The `unstable_rootParams` function has been removed. We are working on an alternative API that we will ship in an upcoming minor release.
......@@ -3,11 +3,7 @@ title: cacheComponents
description: Learn how to enable the cacheComponents flag in Next.js.
---
The `cacheComponents` flag is a feature in Next.js that causes data fetching operations in the App Router to be excluded from prerenders unless they are explicitly cached. This can be useful for optimizing the performance of uncached data fetching in Server Components.
It is useful if your application requires fresh data fetching during runtime rather than serving from a prerendered cache.
It is expected to be used in conjunction with [`use cache`](/docs/app/api-reference/directives/use-cache) so that your data fetching happens at runtime by default unless you define specific parts of your application to be cached with `use cache` at the page, function, or component level.
Cache Components enables component and function-level caching using the [`use cache`](/docs/app/api-reference/directives/use-cache) directive. Data fetching is dynamic by default, and you choose what to cache at the page, component, or function level. Next.js prerenders a static HTML shell that is served immediately while dynamic content streams in when ready, letting you mix static and dynamic content within a single route.
## Usage
......@@ -29,6 +25,8 @@ When `cacheComponents` is enabled, you can use the following cache functions and
- The [`cacheLife` function](/docs/app/api-reference/config/next-config-js/cacheLife) with `use cache`
- The [`cacheTag` function](/docs/app/api-reference/functions/cacheTag)
> **Good to know**: If you used `experimental.useCache` or `experimental.dynamicIO`, migrate using the [Version 16 upgrade guide](/docs/app/guides/upgrading/version-16#experimentaldynamicio-and-experimentalusecache). To migrate route segment configs and other caching patterns, see [Migrating to Cache Components](/docs/app/guides/migrating-to-cache-components).
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.
......
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