What it does
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.
Skills ZICQ category:Agent Workflows mapbox-web-performance-patterns
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.
Official URL:skills.sh
Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.
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.
The official description does not include a separate “Use when”. Per the spec, agents activate this skill when the task matches keywords in that description.
Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Mapbox Performance Patterns Skill; Priority Levels; 🔴 Critical: Eliminate Initialization Waterfalls; Anti-Pattern: Sequential Data Loading; Solution: Parallel Data Loading; Set Precise Initial Viewport.
File analysis: besides SKILL.md, the body references references/data-loading.md, references/interactions.md, references/memory.md, references/mobile.md, references/layers-styles.md. Those resources load on demand.
Mapbox Performance Patterns SkillPriority Levels🔴 Critical: Eliminate Initialization WaterfallsAnti-Pattern: Sequential Data LoadingSolution: Parallel Data LoadingSet Precise Initial ViewportDefer Non-Critical Features🔴 Critical: Optimize Initial Bundle SizeStyle JSON Bundle Impact🟡 High Impact: Optimize Marker CountPerformance ThresholdsAnti-Pattern: Thousands of HTML Markers
Source category:skills.sh agent-skill
namemapbox-web-performance-patternsdescriptionreferences/data-loading.mdreferences/interactions.mdreferences/memory.mdreferences/mobile.mdreferences/layers-styles.mdThese paths are extracted from the text. Check the upstream package to verify the files exist.
Invocation syntax and available tools depend on your Agent client. Client integration guide ↗
Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.
This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.
Copy these instructions to a compatible agent and confirm the target directory matches your client.
Install the agent skill "mapbox-web-performance-patterns" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-cf3e47cb16ff4217-Mapbox-Web-Performance-Patterns.html Save it as .cursor/skills/mapbox-web-performance-patterns/SKILL.md or .claude/skills/mapbox-web-performance-patterns/SKILL.md and keep the frontmatter name and description exactly as-is. This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/mapbox/mapbox-agent-skills instead of creating only a SKILL.md.
Requires Node.js and npx. First inspect the repository's skill list to confirm the name.
npx skills add 'https://github.com/mapbox/mapbox-agent-skills' --list
npx skills add 'https://github.com/mapbox/mapbox-agent-skills' --skill 'mapbox-web-performance-patterns'
The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.
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.
Performance issues are prioritized by their impact on user experience:
Problem: Sequential loading creates cascading delays where each resource waits for the previous one.
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.
// ❌ BAD: Data loads AFTER map initializes
async function initMap() {
const map = new mapboxgl.Map({
container: 'map',
accessToken: MAPBOX_TOKEN,
style: 'mapbox://styles/mapbox/streets-v12'
});
// Wait for map to load, THEN fetch data
map.on('load', async () => {
const data = await fetch('/api/data'); // Waterfall!
map.addSource('data', { type: 'geojson', data: await data.json() });
});
}
Timeline: Map init (0.5s) → Data fetch (1s) = 1.5s total
// ✅ GOOD: Data fetch starts immediately
async function initMap() {
// Start data fetch immediately (don't wait for map)
const dataPromise = fetch('/api/data').then((r) => r.json());
const map = new mapboxgl.Map({
container: 'map',
accessToken: MAPBOX_TOKEN,
style: 'mapbox://styles/mapbox/streets-v12'
});
// Data is ready when map loads
map.on('load', async () => {
const data = await dataPromise;
map.addSource('data', { type: 'geojson', data });
map.addLayer({
id: 'data-layer',
type: 'circle',
source: 'data'
});
});
}
Timeline: Max(map init, data fetch) = ~1s total
// ✅ Set exact center/zoom so the map fetches the right tiles immediately
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v12',
center: [-122.4194, 37.7749],
zoom: 13
});
// Use 'idle' to know when the initial viewport is fully rendered
// (all tiles, sprites, and other resources are loaded; no transitions in progress)
map.once('idle', () => {
console.log('Initial viewport fully rendered');
});
If 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.
// ✅ Load critical features first, defer others
const map = new mapboxgl.Map({
/* config */
});
map.on('load', () => {
// 1. Add critical layers immediately
addCriticalLayers(map);
// 2. Defer secondary features
// Note: Standard style 3D buildings can be toggled via config:
// map.setConfigProperty('basemap', 'show3dObjects', false);
requestIdleCallback(
() => {
addTerrain(map);
addCustom3DLayers(map); // For classic styles with custom fill-extrusion layers
},
{ timeout: 2000 }
);
// 3. Defer analytics and non-visual features
setTimeout(() => {
initializeAnalytics(map);
}, 3000);
});
Impact: Significant reduction in time-to-interactive, especially when deferring terrain and 3D layers
Problem: Large bundles delay time-to-interactive on slow networks.
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.
// ❌ BAD: Inline massive style JSON (can be 500+ KB)
const style = {
version: 8,
sources: {
/* 100s of lines */
},
layers: [
/* 100s of layers */
]
};
// ✅ GOOD: Reference Mapbox-hosted styles
const map = new mapboxgl.Map({
style: 'mapbox://styles/mapbox/streets-v12' // Fetched on demand
});
// ✅ OR: Store large custom styles externally
const map = new mapboxgl.Map({
style: '/styles/custom-style.json' // Loaded separately
});
Impact: Reduces initial bundle by 30-50% when moving from inlined to hosted styles
Problem: Too many markers causes slow rendering and interaction lag.
// ❌ BAD: 5,000 HTML markers = 5+ second render, janky pan/zoom
restaurants.forEach((restaurant) => {
const marker = new mapboxgl.Marker()
.setLngLat([restaurant.lng, restaurant.lat])
.setPopup(new mapboxgl.Popup().setHTML(restaurant.name))
.addTo(map);
});
Result: 5,000 DOM elements, slow interactions, high memory
// ✅ GOOD: GPU-accelerated rendering, smooth at 10,000+ features
map.addSource('restaurants', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: restaurants.map((r) => ({
type: 'Feature',
geometry: { type: 'Point', coordinates: [r.lng, r.lat] },
properties: { name: r.name, type: r.type }
}))
}
});
map.addLayer({
id: 'restaurants',
type: 'symbol',
source: 'restaurants',
layout: {
'icon-image': 'restaurant',
'icon-size': 0.8,
'text-field': ['get', 'name'],
'text-size': 12,
'text-offset': [0, 1.5],
'text-anchor': 'top'
}
});
// Click handler (one listener for all features)
map.on('click', 'restaurants', (e) => {
const feature = e.features[0];
new mapboxgl.Popup().setLngLat(feature.geometry.coordinates).setHTML(feature.properties.name).addTo(map);
});
Performance: 10,000 features render in <100ms
// ✅ GOOD: 50,000 markers → ~500 clusters at low zoom
map.addSource('restaurants', {
type: 'geojson',
data: restaurantsGeoJSON,
cluster: true,
clusterMaxZoom: 14, // Stop clustering at zoom 15
clusterRadius: 50 // Radius relative to tile dimensions (512 = full tile width)
});
// Cluster circle layer
map.addLayer({
id: 'clusters',
type: 'circle',
source: 'restaurants',
filter: ['has', 'point_count'],
paint: {
'circle-color': ['step', ['get', 'point_count'], '#51bbd6', 100, '#f1f075', 750, '#f28cb1'],
'circle-radius': ['step', ['get', 'point_count'], 20, 100, 30, 750, 40]
}
});
// Cluster count label
map.addLayer({
id: 'cluster-count',
type: 'symbol',
source: 'restaurants',
filter: ['has', 'point_count'],
layout: {
'text-field': '{point_count_abbreviated}',
'text-size': 12
}
});
// Individual point layer
map.addLayer({
id: 'unclustered-point',
type: 'circle',
source: 'restaurants',
filter: ['!', ['has', 'point_count']],
paint: {
'circle-color': '#11b4da',
'circle-radius': 6
}
});
Impact: 50,000 markers at 60 FPS with smooth interaction
When building a Mapbox application, verify these optimizations in order:
moveend)map.on('error', …) (or visible error UI) so style/tile/token failures are not silentFirst-pass agent code often ships a map with no map.on('error'), no map.remove(), and a tiny point set that never exercises cluster: true. Production demos need error visibility, teardown, and realistic scale.
// Measure initial load time
console.time('map-load');
map.on('load', () => {
console.timeEnd('map-load');
// isStyleLoaded() returns true when style, sources, tiles, sprites, and models are all loaded
console.log('Style loaded:', map.isStyleLoaded());
});
// Monitor frame rate
let frameCount = 0;
map.on('render', () => frameCount++);
setInterval(() => {
console.log('FPS:', frameCount);
frameCount = 0;
}, 1000);
// Check memory usage (Chrome DevTools -> Performance -> Memory)
Target metrics:
For detailed patterns on specific topics, load the corresponding reference file:
references/data-loading.md — GeoJSON vs Vector Tiles decision matrix, viewport-based loading, progressive loading, vector tiles for large datasetsreferences/interactions.md — Debounce/throttle events, optimize feature queries, batch DOM updatesreferences/memory.md — Map cleanup patterns, popup/marker reuse, feature state vs dynamic layersreferences/mobile.md — Device detection, mobile-optimized layers, touch interaction, constructor optionsreferences/layers-styles.md — Consolidate layers with data-driven styling, simplify expressions, zoom-based visibilityAgent Workflows
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that exte…
Agent Workflows
Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fl…
Agent Workflows
Orchestrate multi-agent teams with defined roles, task lifecycles, handoff protocols, and review workflows. Use when: (1) Setting up a team …
Agent Workflows
Spec-first, TDD, subagent-driven software development workflow. Use when: (1) building any new feature or app — triggers brainstorm → plan →…