# 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

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

## Step-by-Step Migration

### 1. Get Mapbox Access Token

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

### 2. Update Package

```bash
npm uninstall maplibre-gl
npm install mapbox-gl
```

### 3. Update Imports

```javascript
// 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

```javascript
// 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

```javascript
// 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!

```javascript
// 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:**

```javascript
'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

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

## 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

```javascript
// ❌ 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

```javascript
// ❌ 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

```javascript
// ❌ 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:**

```javascript
// ✅ 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)

{
  "skill_name": "mapbox-maplibre-migration",
  "evals": [
    {
      "id": 1,
      "prompt": "I'm migrating a MapLibre GL JS web app to Mapbox GL JS. My app uses custom GeoJSON sources, symbol layers, `fitBounds`, `flyTo`, event handlers, and popups. How much code will I need to change?",
      "expectations": [
        "Reassures the migration is minimal — the APIs are ~95% compatible since MapLibre is a fork of Mapbox GL JS",
        "Lists the actual changes needed: npm install mapbox-gl / remove maplibre-gl, update import, add mapboxgl.accessToken, update style URL",
        "States that GeoJSON sources, symbol layers, fitBounds, flyTo, events, and popups all work identically — no changes needed for these",
        "Explains that all maplibregl. references must be replaced with mapboxgl."
      ]
    },
    {
      "id": 2,
      "prompt": "I migrated my app from MapLibre to Mapbox GL JS by swapping the package and changing the import. Now I get the error: 'A valid Mapbox access token is required to use Mapbox GL JS. Please set mapboxgl.accessToken before creating a map.' Where does the token go?",
      "expectations": [
        "Token must be set as mapboxgl.accessToken = 'pk.xxx' BEFORE calling new mapboxgl.Map()",
        "Shows the correct pattern: set accessToken at the module level, then create the map",
        "Advises storing the token in an environment variable (e.g., process.env.VITE_MAPBOX_TOKEN) and not hardcoding it",
        "Notes the token is NOT passed as a constructor option to the Map — it's a module-level property"
      ]
    },
    {
      "id": 3,
      "prompt": "After migrating from MapLibre to Mapbox GL JS, my geocoder plugin broke. I was using `@maplibre/maplibre-gl-geocoder`. What do I need to do?",
      "expectations": [
        "MapLibre plugins are NOT compatible with Mapbox GL JS — must use the Mapbox equivalent",
        "Install the Mapbox geocoder: @mapbox/mapbox-gl-geocoder",
        "Update the import from MaplibreGeocoder to MapboxGeocoder",
        "Notes that other MapLibre plugins also need Mapbox equivalents — check Mapbox ecosystem for Mapbox-specific versions"
      ]
    }
  ]
}

# API Compatibility Matrix

## 100% Compatible APIs

These work identically in both libraries:

```javascript
// Map methods
map.setCenter([lng, lat]);
map.setZoom(zoom);
map.fitBounds(bounds);
map.panTo([lng, lat]);
map.flyTo({ center, zoom });
map.getCenter();
map.getZoom();
map.getBounds();
map.resize();

// Events
map.on('load', callback);
map.on('click', callback);
map.on('move', callback);
map.on('zoom', callback);
map.on('rotate', callback);

// Markers
new mapboxgl.Marker();
marker.setLngLat([lng, lat]);
marker.setPopup(popup);
marker.addTo(map);
marker.remove();
marker.setDraggable(true);

// Popups
new mapboxgl.Popup();
popup.setLngLat([lng, lat]);
popup.setHTML(html);
popup.setText(text);
popup.addTo(map);

// Sources & Layers
map.addSource(id, source);
map.removeSource(id);
map.addLayer(layer);
map.removeLayer(id);
map.getSource(id);
map.getLayer(id);

// Styling
map.setPaintProperty(layerId, property, value);
map.setLayoutProperty(layerId, property, value);
map.setFilter(layerId, filter);

// Controls
map.addControl(control, position);
new mapboxgl.NavigationControl();
new mapboxgl.GeolocateControl();
new mapboxgl.FullscreenControl();
new mapboxgl.ScaleControl();
```

## Side-by-Side Example

### MapLibre GL JS (Before)

```javascript
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

// No token needed for OSM tiles

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [-122.4194, 37.7749],
  zoom: 12
});

map.on('load', () => {
  new maplibregl.Marker()
    .setLngLat([-122.4194, 37.7749])
    .setPopup(new maplibregl.Popup().setText('San Francisco'))
    .addTo(map);
});
```

### Mapbox GL JS (After)

```javascript
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

// Add your Mapbox token
mapboxgl.accessToken = 'pk.your_mapbox_access_token';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-122.4194, 37.7749],
  zoom: 12
});

map.on('load', () => {
  new mapboxgl.Marker()
    .setLngLat([-122.4194, 37.7749])
    .setPopup(new mapboxgl.Popup().setText('San Francisco'))
    .addTo(map);
});
```

**What's different:** Package, import, token, and style URL. **Everything else is identical.**

# Mapbox-Exclusive Features

After migration, you gain access to these Mapbox-only features:

## Premium Vector Tiles

- **Streets**: Comprehensive road network with names, shields, and routing data
- **Satellite**: High-resolution global imagery updated regularly
- **Terrain**: Elevation data with hillshading and 3D terrain
- **Traffic**: Real-time traffic data (with Navigation SDK)

## Mapbox APIs

Use these APIs alongside your map for enhanced functionality:

```javascript
// Geocoding API - Convert addresses to coordinates
const response = await fetch(
  `https://api.mapbox.com/search/geocode/v6/forward?q=San+Francisco&access_token=${mapboxgl.accessToken}`
);

// Directions API - Get turn-by-turn directions
const directions = await fetch(
  `https://api.mapbox.com/directions/v5/mapbox/driving/-122.42,37.78;-122.45,37.76?access_token=${mapboxgl.accessToken}`
);

// Isochrone API - Calculate travel time polygons
const isochrone = await fetch(
  `https://api.mapbox.com/isochrone/v1/mapbox/driving/-122.42,37.78?contours_minutes=5,10,15&access_token=${mapboxgl.accessToken}`
);
```

## Mapbox Studio

- Visual style editor with live preview
- Dataset management and editing
- Tilesets with custom data upload
- Collaborative team features
- Style versioning and publishing

## Advanced Features (v2.9+)

- **Globe projection**: Seamless transition from globe to Mercator
- **3D buildings**: Extrusion with real building footprints
- **Custom terrain**: Use your own DEM sources
- **Sky layer**: Realistic atmospheric rendering

## Framework Integration

Migration works identically across all frameworks. See `mapbox-web-integration-patterns` skill for detailed React, Vue, Svelte, Angular patterns.

### React Example

```jsx
import { useRef, useEffect } from 'react';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

// Set token once (can be in app initialization)
mapboxgl.accessToken = process.env.REACT_APP_MAPBOX_TOKEN;

function MapComponent() {
  const mapRef = useRef(null);
  const mapContainerRef = useRef(null);

  useEffect(() => {
    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      style: 'mapbox://styles/mapbox/streets-v12',
      center: [-122.4194, 37.7749],
      zoom: 12
    });

    return () => {
      mapRef.current.remove();
    };
  }, []);

  return <div ref={mapContainerRef} style={{ height: '100vh' }} />;
}
```

Just replace `maplibregl` with `mapboxgl` and update token/style - everything else is identical!

### Vue Example

```vue
<template>
  <div ref="mapContainer" class="map-container"></div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN;

const mapContainer = ref(null);
let map = null;

onMounted(() => {
  map = new mapboxgl.Map({
    container: mapContainer.value,
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [-122.4194, 37.7749],
    zoom: 12
  });
});

onUnmounted(() => {
  map?.remove();
});
</script>

<style scoped>
.map-container {
  height: 100vh;
}
</style>
```

# Why Choose Mapbox

## For Production Applications

**Reliability & Support:**

- 99.9% uptime SLA for enterprise customers
- 24/7 support with guaranteed response times
- Dedicated solutions engineers for complex projects
- Regular platform updates and improvements

**Performance:**

- Global CDN for fast tile delivery
- Optimized vector tiles for minimal bandwidth
- Automatic scaling for traffic spikes
- WebGL-accelerated rendering

**Features:**

- Professional cartography and design
- Regular map data updates
- Traffic and routing data
- Premium satellite imagery
- 3D terrain and buildings

## For Development Teams

**Developer Experience:**

- Comprehensive documentation with examples
- Active community and forums
- Regular SDK updates
- TypeScript support (via `@types/mapbox-gl`)
- Extensive example gallery

**Ecosystem Integration:**

- Seamless Studio integration
- API consistency across services
- Mobile SDKs (iOS, Android, React Native)
- Unity and Unreal Engine plugins
- Analytics and monitoring tools

## For Business

**Predictable Costs:**

- Clear, usage-based pricing
- Free tier for development and small apps
- No infrastructure costs
- Scalable pricing for growth

**Compliance & Security:**

- SOC 2 Type II certified
- GDPR compliant
- Enterprise security features
- Audit logs and monitoring

**No Infrastructure Burden:**

- No tile servers to maintain
- No storage or bandwidth concerns
- No update management
- Focus on your application, not infrastructure

## Performance Comparison

Both libraries have similar rendering performance as they share the same core codebase:

| Metric           | Mapbox GL JS                   | MapLibre GL JS         |
| ---------------- | ------------------------------ | ---------------------- |
| **Bundle size**  | ~500KB                         | ~450KB                 |
| **Initial load** | Similar                        | Similar                |
| **Rendering**    | WebGL-based                    | WebGL-based            |
| **Memory usage** | Similar                        | Similar                |
| **Tile loading** | Faster (CDN + optimized tiles) | Depends on tile source |

**Key insight:** Choose based on features, support, and tile quality, not rendering performance. Mapbox's advantage is in tile delivery speed, data quality, and ecosystem integration.