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
styles).
When to Use This Skill
- Migrating an existing Mapbox GL JS app to MapLibre
- Evaluating MapLibre as an open-source alternative to Mapbox
- Understanding API compatibility and what breaks
- Choosing tile sources and services after moving off Mapbox
Why Migrate to MapLibre?
Common reasons teams switch from Mapbox to MapLibre:
- Open-source license — MapLibre is BSD-3-Clause; no vendor lock-in or proprietary terms
- No access token — The library does not require a Mapbox token; tile sources may have their own keys or none (e.g. OpenFreeMap)
- Cost — Avoid Mapbox map-load and API pricing; use free or fixed-cost tile and geocoding providers
- Self-hosting — Use your own tiles (PMTiles, tileserver-gl, martin) or any third-party source
- Community — MapLibre is maintained by the MapLibre organization and community; style spec and APIs evolve in the open
- Community-supported funding — MapLibre is funded by donations from many companies and individuals; there is no single commercial backer, so the project stays aligned with the community
- Open vector tile format (MLT) — MapLibre offers MapLibre Tile (MLT), a modern alternative to Mapbox Vector Tiles (MVT) with better compression and support for 3D coordinates and elevation; supported in GL JS and Native, and generatable with Planetiler
What you give up: Mapbox Studio integration, Mapbox-hosted tiles and styles, Mapbox Search/Directions/Geocoding APIs, official Mapbox support. You replace these with open or third-party alternatives (see maplibre-tile-sources; maplibre-open-search-patterns and maplibre-geospatial-operations not yet in repo).
Understanding the Fork
- Dec 2020: Mapbox GL JS v2.0 switched to a proprietary license. The community forked v1.13 as MapLibre GL JS. MapLibre organization and GL JS repo are the canonical homes.
- API: MapLibre GL JS v1.x is largely backward compatible with Mapbox GL JS v1.x. Most map code (methods, events, layers, sources) works with minimal changes.
- Releases since the fork: MapLibre has moved ahead with its own version line. v2/v3 brought WebGL2, a modern renderer, and features like hillshade and terrain; v4 introduced Promises in public APIs (replacing many callbacks); v5 added globe view and the Adaptive Composite Map Projection. See releases and CHANGELOG.
- Style spec: MapLibre maintains its own MapLibre Style Specification (forked from the Mapbox spec). It is compatible for most styles but has added and diverged in places; check the style spec site when using newer or MapLibre-specific features.
- Ecosystem: Besides GL JS, the MapLibre org hosts MapLibre Native (iOS, Android, desktop), Martin (vector tile server from PostGIS/PMTiles/MBTiles), and the MapLibre Tile (MLT) format. Roadmaps and news: maplibre.org/roadmap, maplibre.org/news.
Step-by-Step Migration
1. Swap the Package
bash
npm uninstall mapbox-gl
npm install maplibre-gl
2. Update Imports and CSS
javascript
// Before (Mapbox)
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
// After (MapLibre)
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
CDN: Replace Mapbox script/link with MapLibre:
- Script:
https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.js
https://unpkg.com/maplibre-gl@*.*.*/dist/maplibre-gl.js
- CSS: same pattern (mapbox-gl.css → maplibre-gl.css).
3. Replace the Namespace
Replace all
with
(and
with
in package names or paths). Examples:
javascript
// Before (Mapbox)
const map = new mapboxgl.Map({ ... });
new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new mapboxgl.NavigationControl());
// After (MapLibre)
const map = new maplibregl.Map({ ... });
new maplibregl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new maplibregl.NavigationControl());
CSS class names: If you style controls or UI by class, rename
to
(and similar prefixes).
4. Remove the Access Token
MapLibre does not use
. Remove any line that sets it:
javascript
// Remove this
mapboxgl.accessToken = process.env.MAPBOX_TOKEN;
Tile and API keys (e.g. for MapTiler or geocoding) are configured per service, not on the map instance. See maplibre-tile-sources for providers that need a key.
5. Replace the Style URL (Critical)
Mapbox styles (
) will not work in MapLibre. You must point the map to a style that uses non-Mapbox tile sources.
Options:
- OpenFreeMap (no key):
style: 'https://tiles.openfreemap.org/styles/liberty'
'https://tiles.openfreemap.org/styles/positron'
- MapTiler (key required): Use a MapTiler style URL (see maplibre-tile-sources)
- Your own style: A style JSON that references vector/raster tile URLs, plus glyphs and sprite (see maplibre-tile-sources; maplibre-style-patterns not yet in repo)
- PMTiles: Use the pmtiles protocol and a .pmtiles URL in your style (see maplibre-pmtiles-patterns)
Example:
javascript
// Before (Mapbox)
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v12',
center: [-122.42, 37.78],
zoom: 12
});
// After (MapLibre)
const map = new maplibregl.Map({
container: 'map',
style: 'https://tiles.openfreemap.org/styles/liberty', // or your chosen style
center: [-122.42, 37.78],
zoom: 12
});
Custom Mapbox styles: If you designed a style in Mapbox Studio, you cannot load it directly in MapLibre. Export the style JSON if possible and replace Mapbox source URLs with a MapLibre-compatible tile source (e.g. OpenMapTiles schema from MapTiler or self-hosted). Layer and paint configuration often stays the same; source and source-layer names may need adjustment (e.g. OpenMapTiles uses
instead of
in some cases).
6. Update Plugins (If Used)
If you use Mapbox-specific plugins, switch to MapLibre or open alternatives. Common equivalents:
| Mapbox Plugin | MapLibre / Alternative |
|---|
@mapbox/mapbox-gl-geocoder
| @maplibre/maplibre-gl-geocoder
|
| @maplibre/maplibre-gl-draw
|
| |
| or community alternatives |
| Mapbox Directions API + UI | (client-side routing with OSRM etc.) or custom + OSRM/OpenRouteService |
Full lists: MapLibre GL JS – Plugins (official docs) and
Made with MapLibre – Plugins (community directory). Many Mapbox plugins work with MapLibre by passing
instead of
; for long-term maintenance, prefer plugins that officially support MapLibre.
Install the MapLibre variant and replace the import and constructor (e.g.
→
where the plugin expects the library reference).
7. Replace Mapbox APIs (Search, Directions, etc.)
If your app calls Mapbox Geocoding, Directions, or other REST APIs, replace them with open or third-party services:
- Geocoding / search: Nominatim, Photon, Pelias, or MapTiler Geocoding (see maplibre-open-search-patterns, not yet in repo)
- Directions / routing: OSRM, OpenRouteService, Valhalla (see maplibre-geospatial-operations, not yet in repo)
Update your code to use the new endpoints and response formats; the map layer and interaction code (e.g. adding a route line) stays the same with MapLibre.
8. What Stays the Same
Most of your map code does not change:
- Map methods: , , , , , etc.
- Events: ,
map.on('click', layerId, callback)
- Markers, popups, controls (Navigation, Geolocate, Fullscreen, Scale)
- Sources and layers: , , ,
- GeoJSON and expressions in the style spec
So after swapping the package, namespace, token, and style (and any plugins/APIs), the rest of your logic can stay as is.
Checklist
Related Skills
- maplibre-tile-sources — Choosing and configuring tile sources (OpenFreeMap, MapTiler, PMTiles, self-hosted)
- maplibre-pmtiles-patterns — Serverless tiles with PMTiles
- maplibre-open-search-patterns — Geocoding and search (Nominatim, Photon, etc.). Not yet in repo.
- maplibre-geospatial-operations — Routing and geometry (OSRM, OpenRouteService, Turf.js). Not yet in repo.
- maplibre-web-integration-patterns — Framework integration (React, Vue, etc.) with MapLibre. Not yet in repo.
Sources Used for This Skill
These sources were used when creating this skill. You may want to involve contributors who maintain or have contributed to them:
- MapLibre official migration guide — maplibre.org/maplibre-gl-js/docs/guides/mapbox-migration-guide/ — Primary step-by-step reference (package, namespace, CSS, CDN).
- MapLibre GL JS documentation — maplibre.org/maplibre-gl-js/docs/ — API and concepts.
- MapLibre GL JS GitHub — github.com/maplibre/maplibre-gl-js — README, releases, and fork history.
- mapbox-agent-skills — The
mapbox-maplibre-migration
- This repo’s skills — maplibre-tile-sources, maplibre-pmtiles-patterns; maplibre-open-search-patterns and maplibre-geospatial-operations not yet in repo — for tile source and service alternatives after migration.