mapbox-web-integration-patterns

# Mapbox Integration Patterns Skill This skill provides official patterns for integrating Mapbox GL JS into web applications using React, Vue, Svelte, Angular, and vanilla JavaScript. These patterns are based on Mapbox's `create-web-app` scaffolding tool and represent production-ready best practices. ## Version Requirements ### Mapbox GL JS **Recommended:** v3.x (latest) - **Minimum:** v3.0.0 - **Why v3.x:** Modern API, improved performance, active development - **v2.x:** Legacy; no longer actively developed (see migration notes below) **Installing via npm (recommended for production):** ```bash npm install mapbox-gl@^3.0.0 # Installs latest v3.x ``` **CDN (for prototyping only):** ```html <!-- Replace VERSION with latest v3.x from https://docs.mapbox.com/mapbox-gl-js/ --> <script src="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.js"></script> <link href="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.css" rel="stylesheet" /> ``` ### Framework Requirements **React:** GL JS works with React 16.8+ (requires hooks). `create-web-app` scaffolds with React 19.x. **Vue:** GL JS works with Vue 2.x+ (Vue 3 Composition API recommended). **Svelte:** GL JS works with any Svelte version. `create-web-app` scaffolds with Svelte 5.x. **Angular:** GL JS works with Angular 2+. `create-web-app` scaffolds with Angular 19.x. **Next.js:** Minimum 13.x (App Router), Pages Router 12.x+. ### Mapbox Search JS ```bash npm install @mapbox/search-js-react@^1.0.0 # React npm install @mapbox/search-js-web@^1.0.0 # Other frameworks ``` ### Version Migration Notes (v2.x to v3.x) - WebGL 2 now required - `optimizeForTerrain` option removed - Improved TypeScript types, better tree-shaking support - No breaking changes to core initialization patterns **Token patterns (work in v2.x and v3.x):** ```javascript const token = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; // Use env vars in production // Global token (works since v1.x) mapboxgl.accessToken = token; const map = new mapboxgl.Map({ container: '...' }); // Per-map token (preferred for multi-map setups) const map = new mapboxgl.Map({ accessToken: token, container: '...' }); ``` ## Core Principles **Every Mapbox GL JS integration must:** 1. Initialize the map in the correct lifecycle hook 2. Store map instance in component state (not recreate on every render) 3. **Always call `map.remove()` on cleanup** to prevent memory leaks 4. Handle token management securely (environment variables) 5. Import CSS: `import 'mapbox-gl/dist/mapbox-gl.css'` ## React Integration (Primary Pattern) **Pattern: useRef + useEffect with cleanup** > **Note:** These examples use **Vite** (the bundler used in `create-web-app`). If using Create React App, replace `import.meta.env.VITE_MAPBOX_ACCESS_TOKEN` with `process.env.REACT_APP_MAPBOX_TOKEN`. See [Token Management Patterns](references/token-management.md) for other bundlers. ```jsx import { useRef, useEffect } from 'react'; import mapboxgl from 'mapbox-gl'; import 'mapbox-gl/dist/mapbox-gl.css'; function MapComponent() { const mapRef = useRef(null); // Store map instance const mapContainerRef = useRef(null); // Store DOM reference useEffect(() => { mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; mapRef.current = new mapboxgl.Map({ container: mapContainerRef.current, center: [-71.05953, 42.3629], zoom: 13 }); // CRITICAL: Cleanup to prevent memory leaks return () => { mapRef.current.remove(); }; }, []); // Empty dependency array = run once on mount return <div ref={mapContainerRef} style={{ height: '100vh' }} />; } ``` **Key points:** - Use `useRef` for both map instance and container - Initialize in `useEffect` with empty deps `[]` - **Always return cleanup function** that calls `map.remove()` - Never initialize map in render (causes infinite loops) ### React + Search JS ```jsx import { useRef, useEffect, useState } from 'react'; import mapboxgl from 'mapbox-gl'; import { SearchBox } from '@mapbox/search-js-react'; import 'mapbox-gl/dist/mapbox-gl.css'; const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; const center = [-71.05953, 42.3629]; function MapWithSearch() { const mapRef = useRef(null); const mapContainerRef = useRef(null); const [inputValue, setInputValue] = useState(''); useEffect(() => { mapboxgl.accessToken = accessToken; mapRef.current = new mapboxgl.Map({ container: mapContainerRef.current, center: center, zoom: 13 }); return () => { mapRef.current.remove(); }; }, []); return ( <> <div style={{ margin: '10px 10px 0 0', width: 300, right: 0, top: 0, position: 'absolute', zIndex: 10 }} > <SearchBox accessToken={accessToken} map={mapRef.current} mapboxgl={mapboxgl} value={inputValue} proximity={center} onChange={(d) => setInputValue(d)} marker /> </div> <div ref={mapContainerRef} style={{ height: '100vh' }} /> </> ); } ``` ## Search JS Integration Summary **Install:** ```bash npm install @mapbox/search-js-react # React npm install @mapbox/search-js-web # Vanilla/Vue/Svelte ``` Both packages include `@mapbox/search-js-core` as a dependency. Only install `-core` directly if building a custom search UI. **Key configuration options:** - `accessToken`: Your Mapbox public token - `map`: Map instance (must be initialized first) - `mapboxgl`: The mapboxgl library reference - `proximity`: `[lng, lat]` to bias results geographically - `marker`: Boolean to show/hide result marker - `placeholder`: Search box placeholder text ### Positioning Search Box **Absolute positioning (overlay):** ```jsx <div style={{ position: 'absolute', top: 10, right: 10, zIndex: 10, width: 300 }} > <SearchBox {...props} /> </div> ``` **Common positions:** - Top-right: `top: 10px, right: 10px` - Top-left: `top: 10px, left: 10px` - Bottom-left: `bottom: 10px, left: 10px` ## Common Mistakes (Critical) ### Mistake 1: Forgetting to call map.remove() ```javascript // BAD - Memory leak! useEffect(() => { const map = new mapboxgl.Map({ ... }) // No cleanup function }, []) // GOOD - Proper cleanup useEffect(() => { const map = new mapboxgl.Map({ ... }) return () => map.remove() // Cleanup }, []) ``` **Why:** Every Map instance creates WebGL contexts, event listeners, and DOM nodes. Without cleanup, these accumulate and cause memory leaks. ### Mistake 2: Initializing map in render ```javascript // BAD - Infinite loop in React! function MapComponent() { const map = new mapboxgl.Map({ ... }) // Runs on every render return <div /> } // GOOD - Initialize in effect function MapComponent() { useEffect(() => { const map = new mapboxgl.Map({ ... }) }, []) return <div /> } ``` **Why:** React components re-render frequently. Creating a new map on every render causes infinite loops and crashes. ### Mistake 3: Not storing map instance properly ```javascript // BAD - map variable lost between renders function MapComponent() { useEffect(() => { let map = new mapboxgl.Map({ ... }) // map variable is not accessible later }, []) } // GOOD - Store in useRef function MapComponent() { const mapRef = useRef() useEffect(() => { mapRef.current = new mapboxgl.Map({ ... }) // mapRef.current accessible throughout component }, []) } ``` **Why:** You need to access the map instance for operations like adding layers, markers, or calling `remove()`. ### Mistake 4: Storing map instance in Vue's data() (Vue-specific) ```javascript // BAD - Vue's reactivity wraps data() objects in a Proxy, breaking mapbox-gl internals! export default { data() { return { map: null // Will be wrapped in a Proxy } }, mounted() { this.map = new mapboxgl.Map({ ... }) // Proxy breaks GL internals } } // GOOD - Assign map as a plain instance property, not in data() export default { mounted() { this.map = new mapboxgl.Map({ container: this.$refs.mapContainer, center: [-71.05953, 42.3629], zoom: 13 }) }, unmounted() { this.map?.remove() } } ``` **Why:** In Vue (especially Vue 3), `data()` properties are wrapped in a `Proxy` for reactivity. Mapbox GL JS internally checks object identity and uses properties that don't survive proxy wrapping. Storing the map in `data()` causes subtle, hard-to-debug failures. Instead, assign the map instance directly as `this.map` in `mounted()` — properties assigned outside `data()` are not made reactive. ### Mistake 5: Silent style/tile failures (no error handler) ```javascript // BAD — blank map when the token/style fails const map = new mapboxgl.Map({ ... }); // GOOD — surface failures map.on('error', (e) => { console.error(e.error || e); // optionally show an on-page error message }); ``` ### Mistake 6: Broken deck.gl CDN via jsDelivr `+esm` ```html <!-- BAD — often throws: does not provide export named 'makeBatchFromTable' --> <script type="module"> import { MapboxOverlay } from 'https://cdn.jsdelivr.net/npm/@deck.gl/mapbox@9.0.0/+esm'; </script> <!-- GOOD — UMD bundle (or esm.sh) --> <script src="https://unpkg.com/deck.gl@9.1.14/dist.min.js"></script> <script> const { MapboxOverlay, ScatterplotLayer } = deck; map.addControl( new MapboxOverlay({ interleaved: false, layers: [ /* ... */ ] }) ); </script> ``` Use `MapboxOverlay` (Mapbox IControl), not a bare `Deck` as a map control. ### Mistake 7: Draw toolbar without `draw.create` If you load `mapbox-gl-draw`, listen for `draw.create` (and update the UI from `draw.getAll()`). Half-deleted handlers that leave a dangling `});` crash the page. ### Mistake 8: Layers lost after `setStyle` (no `style.load` rebind) `map.setStyle(...)` replaces the style tree. Custom sources/layers/handlers added earlier are wiped unless you re-attach them. ```javascript function onStyleReady() { // re-add sources, layers, and interaction handlers here } map.on('style.load', onStyleReady); document.querySelectorAll('[data-style]').forEach((btn) => { btn.addEventListener('click', () => { map.setStyle(btn.dataset.style); // do NOT only add layers on the first 'load' — wait for style.load after every switch }); }); ``` **Agent anti-pattern:** style switcher buttons that call `setStyle` once with no `style.load` rebind. The first style works; every switch after looks broken. ## Reference Files Load these for framework-specific patterns and additional details: - `references/vue.md` — Vue Integration (mounted/unmounted lifecycle) - `references/svelte.md` — Svelte Integration (onMount/onDestroy) - `references/angular.md` — Angular Integration with SSR handling - `references/vanilla.md` — Vanilla JS (Vite) + Vanilla JS (CDN) - `references/web-components.md` — Web Components (basic + reactive + usage in React/Vue/Svelte)