Mapbox Web Performance Patterns

1---2name: mapbox-web-performance-patterns3description: Performance optimization patterns for Mapbox GL JS web applications. Covers initialization waterfalls, bundle size, rendering performance, memory management, and web optimization. Prioritized by impact on user experience.4---5 6# Mapbox Performance Patterns Skill7 8This skill provides performance optimization guidance for building fast, efficient Mapbox applications. Patterns are prioritized by impact on user experience, starting with the most critical improvements.9 10**Performance philosophy:** These aren't micro-optimizations. They show up as waiting time, jank, and repeat costs that hit every user session.11 12## Priority Levels13 14Performance issues are prioritized by their impact on user experience:15 16- **🔴 Critical (Fix First)**: Directly causes slow initial load or visible jank17- **🟡 High Impact**: Noticeable delays or increased resource usage18- **🟢 Optimization**: Incremental improvements for polish19 20---21 22## 🔴 Critical: Eliminate Initialization Waterfalls23 24**Problem:** Sequential loading creates cascading delays where each resource waits for the previous one.25 26**Note:** Modern bundlers (Vite, Webpack, etc.) and ESM dynamic imports automatically handle code splitting and library loading. The primary waterfall to eliminate is **data loading** - fetching map data sequentially instead of in parallel with map initialization.27 28### Anti-Pattern: Sequential Data Loading29 30```javascript31// ❌ BAD: Data loads AFTER map initializes32async function initMap() {33  const map = new mapboxgl.Map({34    container: 'map',35    accessToken: MAPBOX_TOKEN,36    style: 'mapbox://styles/mapbox/streets-v12'37  });38 39  // Wait for map to load, THEN fetch data40  map.on('load', async () => {41    const data = await fetch('/api/data'); // Waterfall!42    map.addSource('data', { type: 'geojson', data: await data.json() });43  });44}45```46 47**Timeline:** Map init (0.5s) → Data fetch (1s) = **1.5s total**48 49### Solution: Parallel Data Loading50 51```javascript52// ✅ GOOD: Data fetch starts immediately53async function initMap() {54  // Start data fetch immediately (don't wait for map)55  const dataPromise = fetch('/api/data').then((r) => r.json());56 57  const map = new mapboxgl.Map({58    container: 'map',59    accessToken: MAPBOX_TOKEN,60    style: 'mapbox://styles/mapbox/streets-v12'61  });62 63  // Data is ready when map loads64  map.on('load', async () => {65    const data = await dataPromise;66    map.addSource('data', { type: 'geojson', data });67    map.addLayer({68      id: 'data-layer',69      type: 'circle',70      source: 'data'71    });72  });73}74```75 76**Timeline:** Max(map init, data fetch) = **~1s total**77 78### Set Precise Initial Viewport79 80```javascript81// ✅ Set exact center/zoom so the map fetches the right tiles immediately82const map = new mapboxgl.Map({83  container: 'map',84  style: 'mapbox://styles/mapbox/streets-v12',85  center: [-122.4194, 37.7749],86  zoom: 1387});88 89// Use 'idle' to know when the initial viewport is fully rendered90// (all tiles, sprites, and other resources are loaded; no transitions in progress)91map.once('idle', () => {92  console.log('Initial viewport fully rendered');93});94```95 96If you know the exact area users will see first, setting `center` and `zoom` upfront avoids the map starting at a default view and then panning/zooming to the target, which wastes tile fetches.97 98### Defer Non-Critical Features99 100```javascript101// ✅ Load critical features first, defer others102const map = new mapboxgl.Map({103  /* config */104});105 106map.on('load', () => {107  // 1. Add critical layers immediately108  addCriticalLayers(map);109 110  // 2. Defer secondary features111  // Note: Standard style 3D buildings can be toggled via config:112  // map.setConfigProperty('basemap', 'show3dObjects', false);113  requestIdleCallback(114    () => {115      addTerrain(map);116      addCustom3DLayers(map); // For classic styles with custom fill-extrusion layers117    },118    { timeout: 2000 }119  );120 121  // 3. Defer analytics and non-visual features122  setTimeout(() => {123    initializeAnalytics(map);124  }, 3000);125});126```127 128**Impact:** Significant reduction in time-to-interactive, especially when deferring terrain and 3D layers129 130---131 132## 🔴 Critical: Optimize Initial Bundle Size133 134**Problem:** Large bundles delay time-to-interactive on slow networks.135 136**Note:** Modern bundlers (Vite, Webpack, etc.) automatically handle code splitting for framework-based applications. The guidance below is most relevant for optimizing what gets bundled and when.137 138### Style JSON Bundle Impact139 140```javascript141// ❌ BAD: Inline massive style JSON (can be 500+ KB)142const style = {143  version: 8,144  sources: {145    /* 100s of lines */146  },147  layers: [148    /* 100s of layers */149  ]150};151 152// ✅ GOOD: Reference Mapbox-hosted styles153const map = new mapboxgl.Map({154  style: 'mapbox://styles/mapbox/streets-v12' // Fetched on demand155});156 157// ✅ OR: Store large custom styles externally158const map = new mapboxgl.Map({159  style: '/styles/custom-style.json' // Loaded separately160});161```162 163**Impact:** Reduces initial bundle by 30-50% when moving from inlined to hosted styles164 165---166 167## 🟡 High Impact: Optimize Marker Count168 169**Problem:** Too many markers causes slow rendering and interaction lag.170 171### Performance Thresholds172 173- **< 100 markers**: HTML markers OK (Marker class)174- **100-10,000 markers**: Use symbol layers (GPU-accelerated)175- **10,000+ markers**: Clustering recommended176- **100,000+ markers**: Vector tiles with server-side clustering177 178### Anti-Pattern: Thousands of HTML Markers179 180```javascript181// ❌ BAD: 5,000 HTML markers = 5+ second render, janky pan/zoom182restaurants.forEach((restaurant) => {183  const marker = new mapboxgl.Marker()184    .setLngLat([restaurant.lng, restaurant.lat])185    .setPopup(new mapboxgl.Popup().setHTML(restaurant.name))186    .addTo(map);187});188```189 190**Result:** 5,000 DOM elements, slow interactions, high memory191 192### Solution: Use Symbol Layers (GeoJSON)193 194```javascript195// ✅ GOOD: GPU-accelerated rendering, smooth at 10,000+ features196map.addSource('restaurants', {197  type: 'geojson',198  data: {199    type: 'FeatureCollection',200    features: restaurants.map((r) => ({201      type: 'Feature',202      geometry: { type: 'Point', coordinates: [r.lng, r.lat] },203      properties: { name: r.name, type: r.type }204    }))205  }206});207 208map.addLayer({209  id: 'restaurants',210  type: 'symbol',211  source: 'restaurants',212  layout: {213    'icon-image': 'restaurant',214    'icon-size': 0.8,215    'text-field': ['get', 'name'],216    'text-size': 12,217    'text-offset': [0, 1.5],218    'text-anchor': 'top'219  }220});221 222// Click handler (one listener for all features)223map.on('click', 'restaurants', (e) => {224  const feature = e.features[0];225  new mapboxgl.Popup().setLngLat(feature.geometry.coordinates).setHTML(feature.properties.name).addTo(map);226});227```228 229**Performance:** 10,000 features render in <100ms230 231### Solution: Clustering for High Density232 233```javascript234// ✅ GOOD: 50,000 markers → ~500 clusters at low zoom235map.addSource('restaurants', {236  type: 'geojson',237  data: restaurantsGeoJSON,238  cluster: true,239  clusterMaxZoom: 14, // Stop clustering at zoom 15240  clusterRadius: 50 // Radius relative to tile dimensions (512 = full tile width)241});242 243// Cluster circle layer244map.addLayer({245  id: 'clusters',246  type: 'circle',247  source: 'restaurants',248  filter: ['has', 'point_count'],249  paint: {250    'circle-color': ['step', ['get', 'point_count'], '#51bbd6', 100, '#f1f075', 750, '#f28cb1'],251    'circle-radius': ['step', ['get', 'point_count'], 20, 100, 30, 750, 40]252  }253});254 255// Cluster count label256map.addLayer({257  id: 'cluster-count',258  type: 'symbol',259  source: 'restaurants',260  filter: ['has', 'point_count'],261  layout: {262    'text-field': '{point_count_abbreviated}',263    'text-size': 12264  }265});266 267// Individual point layer268map.addLayer({269  id: 'unclustered-point',270  type: 'circle',271  source: 'restaurants',272  filter: ['!', ['has', 'point_count']],273  paint: {274    'circle-color': '#11b4da',275    'circle-radius': 6276  }277});278```279 280**Impact:** 50,000 markers at 60 FPS with smooth interaction281 282---283 284## Summary: Performance Checklist285 286When building a Mapbox application, verify these optimizations in order:287 288### 🔴 Critical (Do First)289 290- [ ] Load map library and data in parallel (eliminate waterfalls)291- [ ] Use dynamic imports for map code (reduce initial bundle)292- [ ] Defer non-critical features (terrain, custom 3D layers, analytics)293- [ ] Use symbol layers for > 100 markers (not HTML markers)294- [ ] Implement viewport-based data loading for large datasets295 296### 🟡 High Impact297 298- [ ] Debounce/throttle map event handlers299- [ ] Optimize queryRenderedFeatures with layers filter and bounding box300- [ ] Use GeoJSON for < 5 MB, vector tiles for > 20 MB301- [ ] Always call map.remove() on cleanup in SPAs302- [ ] Reuse popup instances (don't create on every interaction)303- [ ] Use feature state instead of dynamic layers for hover/selection304 305### 🟢 Optimization306 307- [ ] Consolidate multiple layers with data-driven styling308- [ ] Add mobile-specific optimizations (circle layers, disabled rotation)309- [ ] Set minzoom/maxzoom on layers to avoid rendering at irrelevant zoom levels310- [ ] Avoid enabling preserveDrawingBuffer or antialias unless needed311 312### Measurement313 314```javascript315// Measure initial load time316console.time('map-load');317map.on('load', () => {318  console.timeEnd('map-load');319  // isStyleLoaded() returns true when style, sources, tiles, sprites, and models are all loaded320  console.log('Style loaded:', map.isStyleLoaded());321});322 323// Monitor frame rate324let frameCount = 0;325map.on('render', () => frameCount++);326setInterval(() => {327  console.log('FPS:', frameCount);328  frameCount = 0;329}, 1000);330 331// Check memory usage (Chrome DevTools -> Performance -> Memory)332```333 334**Target metrics:**335 336- **Time to Interactive:** < 2 seconds on 3G337- **Frame Rate:** 60 FPS during pan/zoom338- **Memory Growth:** < 10 MB per hour of usage339- **Bundle Size:** < 500 KB initial (map lazy-loaded)340 341---342 343## Reference Files344 345For detailed patterns on specific topics, load the corresponding reference file:346 347- **`references/data-loading.md`** — GeoJSON vs Vector Tiles decision matrix, viewport-based loading, progressive loading, vector tiles for large datasets348- **`references/interactions.md`** — Debounce/throttle events, optimize feature queries, batch DOM updates349- **`references/memory.md`** — Map cleanup patterns, popup/marker reuse, feature state vs dynamic layers350- **`references/mobile.md`** — Device detection, mobile-optimized layers, touch interaction, constructor options351- **`references/layers-styles.md`** — Consolidate layers with data-driven styling, simplify expressions, zoom-based visibility