docs: add migration note for experimental cache flags to cacheComponents#92318
Merged
Conversation
…acheComponents Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Adds migration guidance to the cacheComponents config reference to reduce confusion between legacy experimental flags and the current top-level cacheComponents option.
Changes:
- Adds a “Migrating from experimental flags” section explaining how to switch from
experimental.useCache/experimental.cacheComponentstocacheComponents: true. - Provides a before/after config example and a deprecation note for the experimental flags.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Made-with: Cursor
Made-with: Cursor
- Document deprecated experimental.useCache / experimental.cacheComponents - Use full next.config.ts before/after examples with optional experimental.cacheComponents Made-with: Cursor
…ental flags Made-with: Cursor
Made-with: Cursor
icyJoseph
reviewed
Apr 7, 2026
icyJoseph
reviewed
Apr 7, 2026
icyJoseph
reviewed
Apr 7, 2026
- Rewrite intro to reflect current Cache Components education angle - Update migration section: mention useCache + dynamicIO, drop experimental.cacheComponents, soften deprecation language - Add experimental.useCache to v16 upgrade guide alongside dynamicIO Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
aurorascharff
commented
Apr 10, 2026
…Components.mdx Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
…cache-components-migration-note
Made-with: Cursor
icyJoseph
reviewed
Apr 14, 2026
icyJoseph
approved these changes
Apr 14, 2026
…Components.mdx Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Add a "Migrating from experimental flags" section to the
cacheComponentsconfig reference page, documenting thatexperimental.useCacheandexperimental.cacheComponentsare deprecated in favor of top-levelcacheComponents: 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.mdxshowing the migration from either experimental flag to the top-level config, with a note that both experimental flags are deprecated.