Unverified Commit c8ddbcc1 authored by David Alexandru Ilie's avatar David Alexandru Ilie Committed by GitHub

docs: expand Activity migration guidance

parent 7cb68c12
...@@ -18,7 +18,7 @@ Instead of unmounting pages on navigation, Next.js hides them using React's [`<A ...@@ -18,7 +18,7 @@ Instead of unmounting pages on navigation, Next.js hides them using React's [`<A
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.
> **Good to know:** Use [`useRouter().bfcacheId`](/docs/app/api-reference/functions/use-router#bfcacheid) as a [React `key`](https://react.dev/learn/preserving-and-resetting-state#option-2-resetting-state-with-a-key): a single `<Fragment key={bfcacheId}>` resets an entire subtree on push or replace navigations (including `<Link>` clicks and `router.push` / `router.replace`) while still restoring state on browser back/forward. `bfcacheId` is mainly a migration tool. For new code, prefer the per-pattern resets below. > **Good to know:** Use [`useRouter().bfcacheId`](/docs/app/api-reference/functions/use-router#bfcacheid) as a [React `key`](https://react.dev/learn/preserving-and-resetting-state#option-2-resetting-state-with-a-key): a single `<Fragment key={bfcacheId}>` resets an entire subtree on push or replace navigations (including `<Link>` clicks and `router.push` / `router.replace`) while still restoring state on browser back/forward. It is not a complete opt-out from state preservation. `bfcacheId` is mainly a migration tool. For new code, prefer the per-pattern resets below.
## Choosing what to preserve ## Choosing what to preserve
...@@ -515,6 +515,34 @@ function VideoPlayer({ src }: { src: string }) { ...@@ -515,6 +515,34 @@ function VideoPlayer({ src }: { src: string }) {
When the component becomes visible again, effects re-run and playback position is preserved since the DOM node was never removed. When the component becomes visible again, effects re-run and playback position is preserved since the DOM node was never removed.
### Imperative canvas, map, and editor libraries
Libraries that own DOM state outside React need an explicit hide/show strategy. A map, diagram editor, chart, or canvas may measure its container while it is visible and keep those dimensions internally. Activity preserves that DOM while hiding its container with `display: none`, so the library may need to recalculate its viewport when the route becomes visible again.
For libraries that are inexpensive to initialize, the simplest migration is to create the instance in a layout Effect and destroy it in the cleanup. Activity runs that cleanup when the route is hidden and runs the Effect again when it is shown:
```tsx filename="app/diagram.tsx" highlight={8-14}
'use client'
import { useLayoutEffect, useRef } from 'react'
export function Diagram() {
const containerRef = useRef<HTMLDivElement>(null)
useLayoutEffect(() => {
const container = containerRef.current
if (!container) return
const diagram = createDiagram(container)
return () => diagram.destroy()
}, [])
return <div ref={containerRef} />
}
```
If recreating the instance is too expensive, keep it in a ref, pause subscriptions in the cleanup, and call the library's resize or viewport method when the layout Effect runs again. Test both returning through a link and browser back/forward because both paths can restore preserved UI.
### Distinguishing first mount from re-show ### Distinguishing first mount from re-show
Effects run on every hide-to-visible transition, not just the initial mount. If you need to distinguish the first mount from subsequent visibility changes, use a ref: Effects run on every hide-to-visible transition, not just the initial mount. If you need to distinguish the first mount from subsequent visibility changes, use a ref:
......
...@@ -594,6 +594,14 @@ const nextConfig = { ...@@ -594,6 +594,14 @@ const nextConfig = {
module.exports = nextConfig module.exports = nextConfig
``` ```
### Review preserved UI state
Enabling Cache Components also changes client-side navigation lifecycle. Recently visited routes are hidden with React [`<Activity>`](https://react.dev/reference/react/Activity) instead of being unmounted, so component state, form values, refs, and scroll position can be restored when the user returns.
Before shipping, audit UI that previously relied on unmounting to reset: dialogs, popovers, form status, timers, subscriptions, and imperative canvas, map, or editor libraries. Effects clean up when a route is hidden and run again when it becomes visible, but React and DOM state remain.
[`useRouter().bfcacheId`](/docs/app/api-reference/functions/use-router#bfcacheid) can key a subtree so push and replace navigations start with fresh state. It is not a complete return to the previous behavior because browser back and forward navigation deliberately restores the earlier state. See [Preserving UI state across navigations](/docs/app/guides/preserving-ui-state) for migration patterns and testing guidance.
PPR in **Next.js 16** works differently than in **Next.js 15** canaries. If you are using PPR today, stay in the current Next.js 15 canary you are using. See [Migrating to Cache Components](/docs/app/guides/migrating-to-cache-components) for migration patterns. PPR in **Next.js 16** works differently than in **Next.js 15** canaries. If you are using PPR today, stay in the current Next.js 15 canary you are using. See [Migrating to Cache Components](/docs/app/guides/migrating-to-cache-components) for migration patterns.
```js filename="next.config.js" ```js filename="next.config.js"
......
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