Setting the file. One moment.
Chapter 09 · Mapbox Maplibre Migration
Subchapter 9.4
AGENTS.mdMarkdown8 KBView on GitHub
Quick reference for migrating from MapLibre GL JS to Mapbox GL JS. APIs are ~95% identical - migration is straightforward.
Key advantages:
| Aspect | MapLibre GL JS (Current) | Mapbox GL JS (Target) |
|---|---|---|
| Package | maplibre-gl | mapbox-gl |
| Token | Optional | Required (pk.*) |
| Styles | Custom URL / OSM | mapbox://styles/... |
| Tiles | OSM / Custom | Mapbox premium tiles |
| Support | Community | Official + SLA |
| APIs | Separate | Integrated ecosystem |
| API Compatibility | ~95% identical | ~95% identical |
Key insight: Most of your code stays the same. Only packaging and configuration changes.
# Sign up at mapbox.com
# Get token from account dashboard
# Free tier: 50,000 map loads/monthnpm uninstall maplibre-gl
npm install mapbox-gl// 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';// Required for Mapbox
mapboxgl.accessToken = 'pk.your_mapbox_token';
// Best practice: Use environment variables
mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN;// Before (MapLibre with OSM tiles)
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
center: [-122.4194, 37.7749],
zoom: 12
});
// After (Mapbox with premium tiles)
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v12', // Or any Mapbox style
center: [-122.4194, 37.7749],
zoom: 12
});// All these work identically:
map.setCenter([lng, lat]);
map.setZoom(zoom);
map.fitBounds(bounds);
map.on('click', handler);
new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map);
new mapboxgl.Popup().setHTML(html).addTo(map);
map.addSource(id, source);
map.addLayer(layer);Pre-built styles:
'mapbox://styles/mapbox/standard'; // Mapbox Standard
'mapbox://styles/mapbox/standard-satellite'; // Mapbox Standard Satellite
'mapbox://styles/mapbox/streets-v12'; // Streets v12
'mapbox://styles/mapbox/outdoors-v12'; // Hiking/outdoor
'mapbox://styles/mapbox/light-v11'; // Minimal light
'mapbox://styles/mapbox/dark-v11'; // Minimal dark
'mapbox://styles/mapbox/satellite-v9'; // Satellite imagery
'mapbox://styles/mapbox/satellite-streets-v12'; // Satellite + labels
'mapbox://styles/mapbox/navigation-day-v1'; // Turn-by-turn navigationCustom styles:
'mapbox://styles/your-username/style-id'| MapLibre Plugin | Mapbox Plugin |
|---|---|
@maplibre/maplibre-gl-geocoder | @mapbox/mapbox-gl-geocoder |
@maplibre/maplibre-gl-draw | @mapbox/mapbox-gl-draw |
maplibre-gl-compare | mapbox-gl-compare |
Note: Most Mapbox plugins work directly, no alternatives needed.
100% Compatible APIs:
Only differences:
maplibre-gl vs mapbox-gl)mapbox://)// ❌ Forgot to set token
const map = new mapboxgl.Map({...}); // Error!
// ✅ Set token first
mapboxgl.accessToken = 'pk.your_token';
const map = new mapboxgl.Map({...});// ❌ Using OSM/custom URL
style: 'https://demotiles.maplibre.org/style.json'; // Won't load Mapbox tiles
// ✅ Use Mapbox style URL
style: 'mapbox://styles/mapbox/streets-v12';// ❌ Using MapLibre plugin with Mapbox
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';
// ✅ Use Mapbox plugin
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';✅ Map initializes without errors ✅ Tiles load correctly (Mapbox tiles, not OSM) ✅ Access token configured ✅ Markers/popups display properly ✅ Events fire as expected ✅ Custom layers render correctly ✅ Plugins work (if using Mapbox versions) ✅ No console errors ✅ Performance same or better
Best practices:
// ✅ Use environment variables
mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN;
// ✅ Add URL restrictions in Mapbox dashboard
// Only allow your domains
// ✅ Never commit tokens
// Add .env to .gitignore
// ✅ Use public tokens (pk.*) for client-side
// Never expose secret tokens (sk.*)After migration, you gain access to:
Mapbox APIs:
Mapbox Studio:
Advanced Features:
Mapbox tiles are optimized for:
Expected performance:
Typical migration: 1-2 hours
For large apps: May take 1-2 days including QA
After migration:
Migrate to Mapbox if:
Free tier (50K loads/month) is often sufficient for:
✅ ~95% API compatibility = minimal code changes ✅ Quick migration (1-2 hours typical) ✅ Free tier available for testing ✅ Easy to rollback if needed ✅ No data loss (just configuration changes)