docs: link Activity guide from Cache Components migration guide#92571
docs: link Activity guide from Cache Components migration guide#92571
Conversation
The migration guide covered route segment config replacements but didn't mention the navigation behavior change that comes with Cache Components. Pages are now preserved via React's <Activity> instead of unmounting, which can affect cleanup logic, analytics, and state management. - Add "UI state preservation" section to the migration guide - Add related links to the preserving UI state guide and cacheComponents config - Cross-link the migration guide from the preserving UI state guide Made-with: Cursor
nextjs-bot
added
created-by: Next.js DevEx team
Use bold action summary pattern consistent with other sections in the migration guide. Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Adds bidirectional cross-links between the Cache Components migration guide and the “Preserving UI state” guide, and expands the migration guide to call out the navigation behavior change introduced by Cache Components (pages are preserved via React <Activity> instead of being unmounted).
Changes:
- Add a
relatedsection to the Cache Components migration guide linking to the UI state preservation guide andcacheComponentsconfig reference. - Add a new “UI state preservation” section to the migration guide explaining the preserved-navigation behavior and pointing to recommended patterns.
- Add a
relatedlink from the preserving UI state guide back to the migration guide.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/01-app/02-guides/preserving-ui-state.mdx | Adds a related-link to the Cache Components migration guide for easier discovery. |
| docs/01-app/02-guides/migrating-to-cache-components.mdx | Adds “Next Steps” related links and a new section describing UI state preservation under Cache Components. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Use "hidden" mode terminology matching cacheComponents config reference - Add Effects lifecycle note (cleaned up when hidden, recreated when visible) - Drop display: none implementation detail Made-with: Cursor
Reference the four key patterns from the preserving UI state guide (dropdowns, dialogs, forms, action state) so migrating users know what to look for. Made-with: Cursor
Include "React's Activity component" in the SEO description so searches for "Activity" surface this guide. Made-with: Cursor
| title: Preserving UI state across navigations | ||
| nav_title: Preserving UI state | ||
| description: Learn how to control which UI state is preserved and which resets when navigating between pages. | ||
| description: Learn how React's Activity component preserves UI state across navigations and how to control what resets. |
There was a problem hiding this comment.
@icyJoseph the guide doesnt show up in search results when i search for something like "nextjs activity cache components" so maybe this would be helpful?
There was a problem hiding this comment.
Right, we reframed this to be more about UI that persists, rather than Activity wrapped routes by Cache Components
Interesting that if you drop nextjs from your query then we show the right files
There was a problem hiding this comment.
So should we keep this change?
There was a problem hiding this comment.
Not sure, I think we are missing the Next.js keyword or nextjs - cuz we do mention React and Activity, etc, in the doc, and that's what has more weight on searching
There was a problem hiding this comment.
Okay yep I can add that too
Effect cleanup works normally with Activity — the actual migration concern is that useState/DOM state persists where unmounting previously cleared it. Reframe the lead-in accordingly. Made-with: Cursor
Made-with: Cursor
Action state reset is a sub-case of forms after submission, not a separate pattern to look for. Made-with: Cursor
Made-with: Cursor
Summary
<Activity>instead of unmounting on navigationrelatedlinks pointing to the preserving UI state guide andcacheComponentsconfig referenceThe migration guide previously only covered route segment config replacements (
dynamic,revalidate,fetchCache,runtime) but didn't mention the fundamental navigation behavior change. Users migrating to Cache Components need to know that cleanup logic, analytics events, and state resets may behave differently.