Activity State Management in Next.js with cacheComponents

Why This Skill Exists

When cacheComponents: true is set in next.config.ts, Next.js wraps every route in React's <Activity> component. On client-side navigation, the previous route is not unmounted — instead, Activity switches to mode="hidden". This means:

1. useState values persist — a Dialog that was open stays open when you navigate back
2. DOM is preserved (display: none) — DOM-based side effects (video, audio, iframe) continue running
3. Effects (useEffect/useLayoutEffect) ARE cleaned up on hide and recreated on show — this is your primary reset mechanism
4. Refs remain valid — the DOM nodes still exist in the document tree

This is fundamentally different from the traditional unmount-on-navigate behavior where all state was automatically destroyed. Components that worked fine before cacheComponents can break in subtle ways — a Dropdown that nobody noticed was missing cleanup suddenly stays open after back-navigation.

Step 0: Confirm cacheComponents Is Enabled

Before applying these patterns, check next.config.ts: