mapbox/mapbox-agent-skills

Overview

This skill documents official integration patterns for Mapbox GL JS across popular web frameworks. It focuses on secure token handling, lifecycle-safe initialization and cleanup, search integration, and production-ready setup recommendations. Patterns are rooted in Mapbox's create-web-app scaffolding and target modern versions of Mapbox GL JS and framework toolchains.

How this skill works

The skill describes how to initialize and manage a single Mapbox map instance inside framework lifecycle hooks, how to store the map instance to avoid re-creation, and how to call map.remove() on teardown to prevent memory leaks. It also shows token management via environment variables, options for Search JS integration, and when to prefer npm bundling over CDN for production builds.

When to use it

• When adding an interactive Mapbox GL JS map to React, Vue, Svelte, Angular, Next.js, or vanilla apps.
• When you need safe, repeatable initialization and deterministic cleanup to avoid memory leaks.
• When integrating location search using Mapbox Search JS components.
• When moving from Mapbox GL JS v2.x to v3.x and updating initialization patterns.
• When preparing a production build and wanting stable versioning and tree-shaking.

Best practices

• Install mapbox-gl via npm for production; use CDN only for quick prototypes.
• Pass accessToken to the Map constructor (v3.x preferred) and keep tokens in environment variables.
• Initialize the map in framework-specific mount/init hooks and store the instance in component state or refs.
• Always call map.remove() in the component/unmount/destroy hook to free resources.
• Dynamically import mapbox-gl or guard with isPlatformBrowser on SSR-enabled apps.

Example use cases

• A React app using useRef and useEffect to mount a single map instance with SearchBox for place autocomplete.
• A Vue 3 component that creates the map in mounted() and calls map.remove() in unmounted().
• A Svelte page that binds the map container and cleans up in onDestroy to avoid leaks.
• An Angular standalone component that dynamically imports mapbox-gl and checks isPlatformBrowser before init.
• A vanilla Vite app that imports the CSS, reads VITE_MAPBOX_ACCESS_TOKEN, and initializes the map on load.