mapbox-web-performance-patterns

SKILL.md

Performance optimization patterns for Mapbox GL JS applications, prioritized by user impact.

Eliminate initialization waterfalls by loading map data in parallel with map initialization, and set precise viewport to avoid redundant tile fetches

Use symbol layers for 100+ markers (GPU-accelerated) and clustering for 10,000+ features; avoid HTML markers at scale

Choose GeoJSON for datasets under 5 MB, vector tiles for 20+ MB; implement viewport-based loading to reduce bandwidth

Always call map.remove() on cleanup in single-page applications to prevent memory leaks; reuse popup instances and use feature state for hover effects instead of dynamic layers

Debounce/throttle event handlers, optimize queryRenderedFeatures() with layer filters, and defer non-critical features (terrain, 3D layers) until after initial render

Mapbox Performance Patterns Skill

This 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.

Performance philosophy: These aren't micro-optimizations. They show up as waiting time, jank, and repeat costs that hit every user session.

Priority Levels

Performance issues are prioritized by their impact on user experience:

🔴 Critical (Fix First): Directly causes slow initial load or visible jank

🟡 High Impact: Noticeable delays or increased resource usage

🟢 Optimization: Incremental improvements for polish

🔴 Critical: Eliminate Initialization Waterfalls

Problem: Sequential loading creates cascading delays where each resource waits for the previous one.