Guide for migrating from MapLibre GL JS to Mapbox GL JS, covering API compatibility, token setup, style configuration, and the benefits of Mapbox's official support and ecosystem
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Guide for migrating from MapLibre GL JS to Mapbox GL JS, covering API compatibility, token setup, style configuration, and the benefits of Mapbox's official support and ecosystem
MapLibre to Mapbox Migration Skill
Expert guidance for migrating from MapLibre GL JS to Mapbox GL JS. Covers the shared history, API compatibility, migration steps, and the advantages of Mapbox's platform.
Understanding the Fork
History
MapLibre GL JS is an open-source fork of Mapbox GL JS v1.13.0, created in December 2020 when Mapbox changed their license starting with v2.0.
Timeline:
Pre-2020: Mapbox GL JS was open source (BSD license)
Dec 2020: Mapbox GL JS v2.0 introduced proprietary license
Dec 2020: Community forked v1.13 as MapLibre GL JS
Present: Both libraries continue active development
Key Insight: The APIs are ~95% identical because MapLibre started as a Mapbox fork. Most code works in both with minimal changes, making migration straightforward.
Why Migrate to Mapbox?
Compelling reasons to choose Mapbox GL JS:
Official Support & SLAs: Enterprise-grade support with guaranteed response times
Superior Tile Quality: Best-in-class vector tiles with global coverage and frequent updates
Better Satellite Imagery: High-resolution, up-to-date satellite and aerial imagery
Rich Ecosystem: Seamless integration with Mapbox Studio, APIs, and services
// Before (MapLibre)import maplibregl from'maplibre-gl';
import'maplibre-gl/dist/maplibre-gl.css';
// After (Mapbox)import mapboxgl from'mapbox-gl';
import'mapbox-gl/dist/mapbox-gl.css';
Or with CDN:
<!-- Before (MapLibre) --><scriptsrc="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js"></script><linkhref="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.css"rel="stylesheet" /><!-- After (Mapbox) --><scriptsrc="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js"></script><linkhref="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css"rel="stylesheet" />
4. Add Access Token
// Add this before map initialization
mapboxgl.accessToken = 'pk.your_mapbox_access_token';
Token best practices:
Use environment variables: process.env.VITE_MAPBOX_TOKEN or process.env.NEXT_PUBLIC_MAPBOX_TOKEN
Add URL restrictions in Mapbox dashboard for security
Use public tokens (pk.*) for client-side code
Never commit tokens to git (add to .env and .gitignore)
Rotate tokens if compromised
See mapbox-token-security skill for comprehensive token security guidance.
5. Update Map Initialization
// Before (MapLibre)const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json', // or your custom stylecenter: [-122.4194, 37.7749],
zoom: 12
});
// After (Mapbox)
mapboxgl.accessToken = 'pk.your_mapbox_access_token';
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/standard', // Mapbox stylecenter: [-122.4194, 37.7749],
zoom: 12
});
// Use Mapbox pluginimportMapboxGeocoderfrom'@mapbox/mapbox-gl-geocoder';
Important: This applies to ALL MapLibre plugins, not just the geocoder. Any @maplibre/* or maplibre-gl-* plugin must be replaced with its Mapbox equivalent. Check the Mapbox ecosystem for Mapbox-specific versions of every plugin you use (see Step 8 above for the full mapping table).
Update style URL: Change to mapbox://styles/mapbox/streets-v12
Update all references: Replace maplibregl. with mapboxgl.
Update plugins: Install Mapbox versions of plugins (if used)
Configure token security: Add URL restrictions in dashboard
Test all functionality: Verify map loads, interactions work
Set up billing alerts: Monitor usage in Mapbox dashboard
Update documentation: Document token setup for team
Add .env to .gitignore: Ensure tokens not committed
Quick Reference
Key Differences Summary
What
MapLibre
Mapbox
Package
maplibre-gl
mapbox-gl
Import
import maplibregl from 'maplibre-gl'
import mapboxgl from 'mapbox-gl'
Token
Optional (depends on tiles)
Required: mapboxgl.accessToken = 'pk.xxx'
Style
Custom URL or OSM tiles
mapbox://styles/mapbox/streets-v12
License
BSD (Open Source)
Proprietary (v2+)
Support
Community
Official commercial support
Tiles
Requires tile source
Premium Mapbox tiles included
APIs
Third-party
Full Mapbox API ecosystem
API
~95% compatible
~95% compatible
Bottom line: Migration is easy because APIs are nearly identical. Main changes are packaging, token setup, and style URLs. The result is access to Mapbox's premium tiles, ecosystem, and support.
