/mapbox-maplibre-migration

MapLibre to Mapbox Migration Guide

Quick reference for migrating from MapLibre GL JS to Mapbox GL JS. APIs are ~95% identical - migration is straightforward.

Why Migrate to Mapbox?

Key advantages:

• ✅ Official support and SLAs
• ✅ Premium global tile coverage (streets, satellite, terrain)
• ✅ Mapbox APIs (Geocoding, Directions, Isochrone, Matrix)
• ✅ Mapbox Studio for custom styles (no coding required)
• ✅ Advanced features (Globe view, 3D terrain, better satellite)
• ✅ No infrastructure management (hosted tiles)
• ✅ Predictable costs, free tier: 50,000 map loads/month
• ✅ Enterprise features (compliance, analytics, support)

Migration Overview

Key insight: Most of your code stays the same. Only packaging and configuration changes.

Step-by-Step Migration

1. Get Mapbox Access Token

# Sign up at mapbox.com
# Get token from account dashboard
# Free tier: 50,000 map loads/month

2. Update Package

npm uninstall maplibre-gl
npm install mapbox-gl

3. Update Imports

// 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';

4. Add Access Token

// Required for Mapbox
mapboxgl.accessToken = 'pk.your_mapbox_token';

// Best practice: Use environment variables
mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN;

5. Update Map Initialization

// 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
});

6. Everything Else Stays the Same!

// 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);

Mapbox Style Options

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 navigation

Custom styles:

• Create in Mapbox Studio (visual editor)
• Reference as 'mapbox://styles/your-username/style-id'

Plugin Migration

Note: Most Mapbox plugins work directly, no alternatives needed.

Geocoder migration tip: if the original @maplibre/maplibre-gl-geocoder was configured with countries or language, carry those options over to @mapbox/mapbox-gl-geocoder. Both affect which results come back.

API Compatibility (95%+)

100% Compatible APIs:

• Map methods (all setters/getters)
• Event handling
• Markers and Popups
• Sources and Layers
• Controls
• GeoJSON handling
• Camera animations
• Feature state

Only differences:

• Package name (maplibre-gl vs mapbox-gl)
• Style URL format (custom vs mapbox://)
• Token requirement (optional vs required)
• Some plugins need Mapbox versions

Common Issues

Issue: Missing Token

// ❌ Forgot to set token
const map = new mapboxgl.Map({...});  // Error!

// ✅ Set token first
mapboxgl.accessToken = 'pk.your_token';
const map = new mapboxgl.Map({...});

Issue: Wrong Style Format

// ❌ 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';

Issue: Plugin Compatibility

// ❌ Using MapLibre plugin with Mapbox
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

// ✅ Use Mapbox plugin
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

Testing Checklist

✅ 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

Token Security

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.*)

Mapbox Ecosystem Benefits

After migration, you gain access to:

Mapbox APIs:

• Geocoding API (forward/reverse)
• Directions API (routing, turn-by-turn)
• Isochrone API (time/distance polygons)
• Matrix API (distance matrices)
• Tilequery API (feature lookup)

Mapbox Studio:

• Visual style editor (no coding)
• Dataset editor
• Tileset management
• Style publishing

Advanced Features:

• Globe view (3D Earth)
• 3D terrain with real elevations
• Premium satellite imagery
• Traffic-aware routing
• Real-time updates

Performance Notes

Mapbox tiles are optimized for:

• Fast loading (global CDN)
• Smaller file sizes (vector tiles)
• Better caching
• Consistent quality worldwide

Expected performance:

• Similar or better rendering speed
• Potentially faster tile loading (Mapbox CDN)
• Same memory usage
• Identical frame rates

Migration Timeline

Typical migration: 1-2 hours

1. Setup (15 min): Get token, update packages
2. Code changes (30 min): Update imports, add token, change style URL
3. Testing (30 min): Verify all features work
4. Deployment (15 min): Deploy and monitor

For large apps: May take 1-2 days including QA

Support & Resources

After migration:

• Official Mapbox support (for paid plans)
• Extensive documentation
• Code examples
• Community forums
• Enterprise SLAs (for enterprise plans)

Quick Decision: Should I Migrate?

Migrate to Mapbox if:

• ✅ Want official support
• ✅ Need Mapbox APIs (Geocoding, Directions)
• ✅ Want better tile quality/coverage
• ✅ Prefer no infrastructure management
• ✅ Need enterprise features
• ✅ Want Mapbox Studio for styling
• ✅ Building production applications

Free tier (50K loads/month) is often sufficient for:

• Small-medium websites
• Internal tools
• MVPs and prototypes
• Many business applications

Migration is Low Risk

✅ ~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)