mapbox-web-performance-patterns_skill

Overview

This skill delivers prioritized performance optimization patterns for Mapbox GL JS web applications. It focuses on changes that measurably improve time-to-interactive, rendering smoothness, and long-term memory stability. Guidance is actionable, with code patterns and trade-offs for initialization, bundling, data loading, rendering, and cleanup.

How this skill works

The skill inspects common Mapbox integration patterns and highlights high-impact anti-patterns and their fixes. It explains parallelizing data fetches, reducing initial bundle weight, choosing the right data transport (GeoJSON vs vector tiles), and scaling markers and interactions. Practical code snippets show how to preload tiles, debounce events, cluster points, and clean up resources to prevent leaks.

When to use it

• On first load to reduce time-to-interactive and eliminate visible jank
• When bundle size or initial style JSON slows page load
• If map interactions become janky during pan/zoom or with many markers
• When serving large datasets or needing viewport-based loading
• Before shipping to ensure cleanup of map instances in SPAs

Best practices

• Fetch critical data in parallel with map initialization to avoid waterfalls
• Reference hosted or external styles instead of inlining large style JSON
• Render many points with symbol layers, canvas, or clustering instead of thousands of DOM markers
• Use vector tiles for large or global datasets; prefer GeoJSON for small, frequently changing data
• Throttle/debounce heavy event handlers and run expensive work on moveend/idle
• Always remove listeners, layers, sources, controls and call map.remove() on teardown

Example use cases

• A single-page app that needs fast map time-to-interactive by fetching GeoJSON while the map initializes
• A listing site replacing 5,000 HTML markers with a symbol layer for sub-100ms renders
• A map showing a continent-scale dataset where vector tiles replace a massive GeoJSON download
• Progressive loading: show simplified features first, then stream detailed geometry in background
• An analytics dashboard that batches DOM updates with requestAnimationFrame to maintain 60 FPS