maplibre-mapbox-migration
Installation
SKILL.md
Mapbox to MapLibre Migration
This skill guides you through migrating an application from Mapbox GL JS to MapLibre GL JS. The two libraries share a common ancestry (MapLibre forked from Mapbox GL JS v1.13 in December 2020), so the API is largely the same. The main changes are: swap the package, replace the namespace, remove the Mapbox access token, and choose a new tile source (MapLibre does not use mapbox:// styles).
When to Use This Skill
- Migrating an existing Mapbox GL JS app to MapLibre
- Choosing tile sources and services after moving off Mapbox
Migration at a Glance
Work through these in order; each item has a numbered step below.
- 1. Uninstall
mapbox-gl, installmaplibre-gl; replace imports and CSS - 2. Replace all
mapboxglwithmaplibregl(and CSS classesmapboxgl-→maplibregl-) - 3. Remove
mapboxgl.accessToken; setstyleto a non-Mapbox URL (hosted or your own style) - 4. Convert callbacks to promises, replace Mapbox v2-only APIs (
setFog→setSky, free camera →calculateCameraOptionsFromCameraLngLatAltRotation+jumpTo/easeTo/flyTo), and check the table of later MapLibre behavior changes - 5. Replace Mapbox Geocoding/Directions with Nominatim, OSRM, or other open alternatives, and replace or verify each Mapbox plugin
- 6. Test map load, controls, and any API-driven features