Add mapbox-performance-patterns skill

[mattpodwysocki]

Summary

Introduces a new Agent Skill that provides performance optimization guidance for Mapbox applications, inspired by Vercel's react-best-practices but focused on map-specific performance patterns.

Just like Vercel's guide helps LLMs make informed decisions about React performance, this skill teaches AI assistants how to build fast, efficient Mapbox applications by providing concrete, actionable patterns prioritized by impact.

Motivation

AI assistants need structured, authoritative guidance on Mapbox performance to:

• Avoid common anti-patterns (e.g., thousands of HTML markers)
• Make informed decisions (e.g., GeoJSON vs vector tiles)
• Prioritize high-impact optimizations over micro-optimizations
• Provide concrete code examples with before/after comparisons

Similar to how react-best-practices reduces hallucination by providing canonical patterns, this skill ensures LLMs recommend proven Mapbox performance techniques.

What's Included

🔴 Critical (Fix First)

Patterns that directly cause slow initial load or visible jank:

• Eliminate initialization waterfalls - Parallel loading of map library + data
• Optimize initial bundle size - Dynamic imports, lazy loading, code splitting

🟡 High Impact

Patterns that create noticeable delays or resource usage:

• Optimize marker count - HTML vs Canvas vs Symbol layers, clustering thresholds
• Data loading strategies - GeoJSON vs vector tiles decision matrix, viewport-based loading
• Event handling optimization - Debouncing, throttling, batch DOM updates

🟢 Optimization

Patterns for incremental improvements:

• Memory management - Cleanup patterns, feature state vs dynamic layers
• Mobile optimizations - Battery awareness, touch events, simplified rendering
• Layer consolidation - Reducing draw calls, pre-computing expressions

Structure

Each pattern includes:

• ❌ Anti-pattern example (what NOT to do) with explanation
• ✅ Solution example with code
• Performance impact measurements
• Decision matrices for choosing between approaches (e.g., GeoJSON vs vector tiles)
• Thresholds for when to apply patterns (e.g., < 100 markers = HTML OK)

Examples

Eliminate Waterfalls

// ❌ BAD: 2.5s sequential waterfall
async function initMap() {
  await import('mapbox-gl');              // Wait 1: 1s
  const map = new mapboxgl.Map({...});    // Wait 2: 0.5s
  map.on('load', async () => {
    const data = await fetch('/api/data'); // Wait 3: 1s
  });
}

// ✅ GOOD: 1s parallel loading
async function initMap() {
  const [mapboxgl, mapData] = await Promise.all([
    import('mapbox-gl'),
    fetch('/api/data').then(r => r.json())
  ]);
  // Total time = max(1s, 1s) = 1s
}

Marker Performance

Marker Count	Use
< 100	HTML markers (Marker class)
100-1,000	Symbol layers (GeoJSON)
1,000-10,000	Clustering required
> 10,000	Server-side clustering + vector tiles

GeoJSON vs Vector Tiles

Scenario	Use GeoJSON	Use Vector Tiles
< 1 MB data	✅	❌
1-10 MB data	⚠️ Consider	✅
> 10 MB data	❌	✅
Data changes frequently	✅	❌

Performance Checklist

The skill includes a prioritized checklist:

🔴 Critical (Do First)

• Load map library and data in parallel
• Use dynamic imports for map code
• Defer non-critical features
• Use clustering for > 100 markers
• Implement viewport-based loading

🟡 High Impact

• Debounce/throttle event handlers
• Optimize queryRenderedFeatures
• Choose appropriate data format
• Implement progressive loading

🟢 Optimization

• Always call map.remove() on cleanup
• Reuse popup instances
• Use feature state vs dynamic layers
• Consolidate layers
• Add mobile optimizations

Comparison to Vercel's react-best-practices

Vercel's Guide	This Skill
Eliminate waterfalls	✅ Parallel map library + data loading
Reduce bundle size	✅ Dynamic imports, lazy loading plugins
Prevent re-renders	✅ Feature state vs layer creation
Optimize rendering	✅ Symbol layers vs HTML markers
Mobile performance	✅ Battery awareness, simplified rendering

Value for LLMs

Like Vercel's react-best-practices, this skill:

• Reduces hallucination by providing canonical patterns
• Prioritizes by impact (critical → high → optimization)
• Provides concrete examples with before/after code
• Includes decision matrices for choosing between approaches
• Focuses on real user pain (waiting time, jank, battery drain)
• Works as RAG for coding - authoritative guidance at inference time

Testing

To test this skill:

1. Symlink to Claude Code:

   mkdir -p .claude
   ln -s ../skills .claude/skills

2. Test prompts:

   • "How do I optimize a Mapbox map with 5,000 markers?"
   • "What's the best way to load large GeoJSON files?"
   • "My map is slow on mobile, what should I optimize first?"
   • "Should I use GeoJSON or vector tiles for 50 MB of data?"

Expected: Claude cites specific patterns from the skill with priority levels and code examples.

Documentation

Updated skills/README.md to include:

• Skill description and use cases
• Key topics covered
• When to use this skill
• Example scenarios

Related

• Inspired by: Vercel react-best-practices
• Complements: mapbox-integration-patterns (setup), mapbox-style-patterns (styling)
• Differs from: mapbox-style-quality (validation/checks) - this focuses on runtime performance

🤖 Generated with Claude Code