React 18 and Mapbox GL JS: Synchronizing External State with Imperative Camera APIs

Recommended Pattern: Guarded Imperative Sync with Mounted Flag

The reliable approach combines a ref for the Mapbox instance, a mounted flag ref, and a subscription to the external store that only applies changes after map.loaded() resolves. This prevents drift during React 18's development-only double-mount cycle.

Core Implementation

import { useEffect, useRef } from 'react';
import mapboxgl from 'mapbox-gl';
import { useStore } from './store'; // Zustand/Redux hook

export function useMapSync(containerRef) {
  const mapRef = useRef(null);
  const mountedRef = useRef(false);
  const { center, zoom, bearing, pitch, setViewport } = useStore();

  useEffect(() => {
    if (!containerRef.current || mapRef.current) return;

    // Read initial values once at mount time — no stale closure
    const initialViewport = useStore.getState();
    const map = new mapboxgl.Map({
      container: containerRef.current,
      center: initialViewport.center,
      zoom: initialViewport.zoom,
      bearing: initialViewport.bearing ?? 0,
      pitch: initialViewport.pitch ?? 0,
      style: 'mapbox://styles/mapbox/streets-v12',
    });

    mapRef.current = map;
    mountedRef.current = true;

    // Wait for map to be ready before accepting external updates
    map.once('load', () => {
      if (!mountedRef.current) return; // Guard against cleanup race
      // Map is ready; external subscriptions can now apply safely
    });

    // Throttled emission from map → store (avoid 'move' flood)
    const onMoveEnd = () => {
      if (!mountedRef.current) return;
      const { center, zoom, bearing, pitch } = map.getContainer() ? map.getViewport() : {};
      if (center) setViewport({ center, zoom, bearing, pitch });
    };
    map.on('moveend', onMoveEnd);

    return () => {
      mountedRef.current = false; // Synchronously block new imperative calls
      map.off('moveend', onMoveEnd);
      map.off('load', () => {});
      map.remove();
      mapRef.current = null;
    };
  }, [containerRef, setViewport]);

  // Subscribe to external store → map (imperative)
  useEffect(() => {
    if (!mountedRef.current || !mapRef.current?.loaded()) return;
    mapRef.current.jumpTo({ center, zoom, bearing, pitch });
  }, [center, zoom, bearing, pitch]);

  return mapRef;
}

Why This Prevents Drift

• Strict Mode double-mount: The first effect runs, creates map, sets mounted=true. React immediately unmounts (cleanup runs, mounted=false, map removed). Second mount creates fresh instance. The flag ensures no external updates apply to the orphaned first instance.
• Stale closures in map.on('load'): Initial viewport is read via useStore.getState() at mount time, not captured in closure. The subscription effect reads current store values on each change.
• Race between map.remove() and store updates: mountedRef.current is checked synchronously before any jumpTo/flyTo call.

Cleanup Requirements

1. Set mountedRef.current = false first — blocks in-flight store updates from touching the dying instance.
2. Remove all Mapbox listeners (moveend, load, any custom).
3. Call map.remove() to release WebGL context and DOM handlers.
4. Null the map ref.

Verification Checklist

• Run in React 18 + Vite with <React.StrictMode>; no console errors on hot reload.
• Simulate rapid external updates (e.g., setInterval changing center every 200 ms); camera follows without "map not loaded" errors.
• Conditionally unmount map component; heap snapshot shows no detached Mapbox listeners or map instances.

One diagnostic detail: Are you using react-map-gl v7+ or raw Mapbox GL JS? The wrapper's useMap hook changes where the loaded() promise lives, but the mounted-flag guard pattern remains the same.