mapbox-web-integration-patterns

This skill provides official patterns for integrating Mapbox GL JS into web applications across popular frameworks: React (the primary pattern), Vue, Svelte, Angular, Next.js, and vanilla JavaScript. It is based on Mapbox's create-web-app scaffolding tool and captures production-ready best practices. The problem it addresses is that GL JS is a stateful, WebGL-based library that must be initialized in the right lifecycle hook, kept out of the render path, and explicitly torn down; getting this wrong causes memory leaks, infinite re-render loops, and broken server-side rendering.

It documents version requirements (GL JS v3.x recommended, minimum v3.0.0, with v2-to-v3 migration notes such as the WebGL 2 requirement) and framework version compatibility, plus Mapbox Search JS packages. Core principles apply to every integration: initialize in the correct hook, store the map instance in a ref or component state rather than recreating it, always call map.remove() on cleanup, import the GL JS CSS, and handle tokens securely through environment variables. Framework-specific reference files show the useRef plus useEffect cleanup pattern for React, the 'use client' directive and NEXT_PUBLIC_ env vars for Next.js App Router, dynamic ssr:false imports for Pages Router, and equivalents for Vue, Svelte, Angular, web components, and vanilla JS, along with token-management and common-mistakes references and an evals set.

It targets frontend and full-stack developers embedding interactive Mapbox maps. Its security guidance is defensive: it consistently recommends storing access tokens in environment variables rather than hardcoding them, and it involves no destructive or risky operations.