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

docs: link Activity guide from Cache Components migration guide (#92571)

## Summary

- Add a "UI state preservation" section to the Cache Components
migration guide explaining that pages are now preserved via React's
`<Activity>` instead of unmounting on navigation
- Add `related` links pointing to the preserving UI state guide and
`cacheComponents` config reference
- Cross-link the migration guide from the preserving UI state guide for
bidirectional discovery

The 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.

---------
Co-authored-by: 's avatarJoseph Chamochumbi <joseph.chamochumbi@vercel.com>
parent 645eef54
...@@ -8,6 +8,7 @@ related: ...@@ -8,6 +8,7 @@ related:
- app/getting-started/revalidating - app/getting-started/revalidating
- app/api-reference/directives/use-cache - app/api-reference/directives/use-cache
- app/api-reference/config/next-config-js/cacheComponents - app/api-reference/config/next-config-js/cacheComponents
- app/guides/preserving-ui-state
--- ---
{/* AI agent hint: To ensure client-side navigations are instant with Cache Components, export `unstable_instant` from the route. See docs/01-app/02-guides/instant-navigation.mdx */} {/* AI agent hint: To ensure client-side navigations are instant with Cache Components, export `unstable_instant` from the route. See docs/01-app/02-guides/instant-navigation.mdx */}
......
...@@ -2,6 +2,12 @@ ...@@ -2,6 +2,12 @@
title: Migrating to Cache Components title: Migrating to Cache Components
nav_title: Migrating to Cache Components nav_title: Migrating to Cache Components
description: Learn how to migrate from route segment configs to Cache Components in Next.js. description: Learn how to migrate from route segment configs to Cache Components in Next.js.
related:
title: Next Steps
description: Learn about other behavior changes when Cache Components is enabled.
links:
- app/guides/preserving-ui-state
- app/api-reference/config/next-config-js/cacheComponents
--- ---
When [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled, route segment configs like `dynamic`, `revalidate`, and `fetchCache` are replaced by [`use cache`](/docs/app/api-reference/directives/use-cache) and [`cacheLife`](/docs/app/api-reference/functions/cacheLife). When [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled, route segment configs like `dynamic`, `revalidate`, and `fetchCache` are replaced by [`use cache`](/docs/app/api-reference/directives/use-cache) and [`cacheLife`](/docs/app/api-reference/functions/cacheLife).
...@@ -173,3 +179,15 @@ export default async function Page() { ...@@ -173,3 +179,15 @@ export default async function Page() {
## `runtime = 'edge'` ## `runtime = 'edge'`
**Not supported.** Cache Components requires the Node.js runtime. Switch to the Node.js runtime (the default) by removing the `runtime = 'edge'` export. If you need edge behavior for specific routes, use [Proxy](/docs/app/api-reference/file-conventions/proxy) instead. **Not supported.** Cache Components requires the Node.js runtime. Switch to the Node.js runtime (the default) by removing the `runtime = 'edge'` export. If you need edge behavior for specific routes, use [Proxy](/docs/app/api-reference/file-conventions/proxy) instead.
## UI state preservation
**Component state now persists across navigations.** With Cache Components, Next.js preserves routes using React's [`<Activity>`](https://react.dev/reference/react/Activity) component in [`"hidden"`](https://react.dev/reference/react/Activity#activity) mode instead of unmounting them. Effects clean up and re-run normally, but `useState` values, form inputs, and scroll position are no longer reset when navigating away and back.
If your code relied on unmounting to clear state, you may need to add explicit reset logic:
- **Dropdowns and popovers** — stay open when navigating back. Close them in a `useLayoutEffect` cleanup function.
- **Dialogs with initialization logic** — Effects that depend on dialog state (like focusing an input) won't re-fire if the state was preserved. Derive dialog state from the URL instead.
- **Forms after submission** — input values and `useActionState` results (success/error messages) persist when returning. Reset in the submit handler or user action when possible, otherwise use a cleanup effect.
See [Preserving UI state across navigations](/docs/app/guides/preserving-ui-state) for detailed examples of each pattern.
--- ---
title: Preserving UI state across navigations title: How Next.js preserves UI state with Activity
nav_title: Preserving UI state 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 in Next.js and how to control what resets.
related: related:
title: Related title: Related
description: Learn more about Cache Components and preserving UI state. description: Learn more about Cache Components and preserving UI state.
links: links:
- app/getting-started/caching - app/getting-started/caching
- app/guides/migrating-to-cache-components
--- ---
> **Good to know:** This guide assumes [Cache Components](/docs/app/getting-started/caching) is enabled. Enable it by setting [`cacheComponents: true`](/docs/app/api-reference/config/next-config-js/cacheComponents) in your Next config file. > **Good to know:** This guide assumes [Cache Components](/docs/app/getting-started/caching) is enabled. Enable it by setting [`cacheComponents: true`](/docs/app/api-reference/config/next-config-js/cacheComponents) in your Next config file.
Before Cache Components, preserving page-level state across navigations required workarounds like hoisting state to a [shared layout](/docs/app/getting-started/layouts-and-pages#nesting-layouts) or using an external store. With Cache Components, Next.js preserves state and DOM out of the box. Before Cache Components, preserving page-level state across navigations required workarounds like hoisting state to a [shared layout](/docs/app/getting-started/layouts-and-pages#nesting-layouts) or using an external store. With Cache Components, Next.js preserves state and DOM out of the box.
Instead of unmounting pages on navigation, Next.js hides them using React's [`<Activity>`](https://react.dev/reference/react/Activity) component. The DOM nodes stay in the document (hidden with `display: none`), so both React state and DOM state are preserved: form drafts, scroll positions, expanded `<details>` elements, video playback progress, and more. Instead of unmounting pages on navigation, Next.js hides them using React's [`<Activity>`](https://react.dev/reference/react/Activity) component. Activity keeps the DOM in the document (hidden with `display: none`), so both React state and DOM state are preserved: form drafts, scroll positions, expanded `<details>` elements, video playback progress, and more.
Next.js preserves up to 3 routes. Beyond that, the oldest route is evicted and will re-render fresh. Next.js preserves up to 3 routes. Beyond that, the oldest route is evicted and will re-render fresh.
......
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