Improve docs about handling state during navigation with cacheComponents

[gmoniava]

Goals

1. Improve docs about handling state during navigation with cacheComponents

Background

Based on the docs with cacheComponents, routes are hidden via React <Activity> (state preserved) or fully unmounted (state lost) based on heuristics:

"Next.js uses heuristics to keep a few recently visited routes "hidden", while older routes are removed from the DOM to prevent excessive growth."

Because state may or may not survive navigation, app authors lack a clear mental model for building pages safely:

• Can route-level state be relied on at all?
• Should routes always be treated as disposable?
• How should developers choose between local state, URL state, or external stores?

Proposal

It would help if the docs clearly framed cached route state as a performance optimization (not a correctness guarantee) and provided guidance on patterns that are safe regardless of whether a route is hidden or unmounted.
Thanks!

[gmoniava]

I found a gh comment related to this.

[icyJoseph]

There's a guide on canary about this: https://github.com/vercel/next.js/blob/canary/docs/01-app/02-guides/preserving-ui-state.mdx - just needs to be published to the live site - which should happen rather soon

[icyJoseph]

Guide lives here now: https://nextjs.org/docs/app/guides/preserving-ui-state

[gmoniava]

@icyJoseph Thanks. Imho would be nice if this Activity is optional, in order to avoid extra code.