Docs: Preserving UI State guide missing warning for imperative DOM/WebGL libraries (Mapbox GL, Three.js, etc.)

[AbdulSamad94]

What is the documentation issue?

The cacheComponents docs mention that effects are cleaned up on hide and recreated on reappear, and links to the Preserving UI State guide for common patterns. However, the guide's "Effect and media cleanup" section only covers timers and media elements <video>, <audio>, it's missing a critical third category

Libraries like Mapbox GL, Three.js, Leaflet, and Google Maps destroy their internal DOM references during useEffect cleanup (e.g., map.remove() sets _container = null). When Activity reappears the route, effects re-run but the library instance is in a "destroyed" state, leading to a crash:

TypeError: Cannot read properties of undefined (reading 'appendChild')
    at Marker.addTo
    at recursivelyTraverseReappearLayoutEffects

Critical detail: This only crashes in production builds (Webpack). Dev mode (Turbopack) never triggers it, making it extremely difficult to diagnose.

Proposed Fix: Remount the library from scratch on reappear instead of reusing the stale, destroyed instance.

A warning and example for this pattern in the Preserving UI State guide would prevent significant debugging time for anyone using mapping, 3D, or canvas-based libraries.

Is there any context that might help us understand?

Context:

• Confirmed with Next.js 16 + react-map-gl v8 / Mapbox GL JS v3.
• Related to issue [cacheComponents] Activity component route preservation causes significant breakage in application logic, UI behavior and E2E tests #86577.

I'd be happy to contribute a docs PR adding this pattern to the Preserving UI State guide if the team confirms the recommended approach. Let me know if this would be welcomed.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/guides/preserving-ui-state

[icyJoseph]

Hi, we haven't forgotten about this.

I had figured out instantsearch for example: #85720

There is one more thing, as mentioned in #86577 - probably buried by Github UI - that we will be updating the framework with.

As pointed out in #85720, a key={} instance remount does the trick:

For the time being you can use a different key generated above the InstantSearch component, unfortunately techniques to generate a key and re-render can be expensive... but for the time being it would do the trick, creating a new whole InstantSearch component instance.

[AbdulSamad94]

Hi, we haven't forgotten about this.

I had figured out instantsearch for example: #85720

There is one more thing, as mentioned in #86577 - probably buried by Github UI - that we will be updating the framework with.

As pointed out in #85720, a key={} instance remount does the trick:

For the time being you can use a different key generated above the InstantSearch component, unfortunately techniques to generate a key and re-render can be expensive... but for the time being it would do the trick, creating a new whole InstantSearch component instance.

Thanks for the context! Happy to open a PR for the docs if that's helpful.