Mapbox Maplibre Migration
Migrate an existing MapLibre GL JS map stack to Mapbox GL JS with token, style, and package swaps while keeping ~95% of map API code intact.
Overview
Mapbox MapLibre Migration is an agent skill for the Build phase that walks solo builders through moving MapLibre GL JS apps to Mapbox GL JS with token, style, and package updates.
Install
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-maplibre-migrationWhat is this skill?
- Documents ~95% API parity between MapLibre GL JS and Mapbox GL JS
- Step-by-step migration: package swap maplibre-gl → mapbox-gl and required access token (pk.*)
- Compares styles, tiles, and integrated Mapbox APIs vs OSM or custom tile URLs
- Calls out Mapbox free tier context (50,000 map loads/month) and hosted premium tiles
- ~95% API compatibility between MapLibre GL JS and Mapbox GL JS
- 50,000 map loads/month cited for Mapbox free tier context
Adoption & trust: 629 installs on skills.sh; 64 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your map app runs on MapLibre and community tiles but you need Mapbox support, SLAs, and Studio styles without a full rewrite.
Who is it for?
Indie SaaS or mobile products with an in-app map that already uses MapLibre and wants Mapbox tiles, Studio, and billing predictability.
Skip if: Greenfield map apps with no MapLibre code yet—start with a Mapbox GL JS starter instead—or teams that must stay fully offline on self-hosted tiles only.
When should I use this skill?
When refactoring an existing MapLibre GL JS codebase to Mapbox GL JS and you need package, token, and style migration steps in one place.
What do I get? / Deliverables
You end up with mapbox-gl installed, a valid pk token, Mapbox style URLs, and a migration checklist so existing layer and camera code largely carries over.
- Updated mapbox-gl dependency and configuration
- Migration-aligned style and token setup notes applied in the codebase
Recommended Skills
Journey fit
How it compares
Use this migration guide instead of guessing package renames; it is documentation skill content, not a hosted Mapbox MCP or tile CDN.
Common Questions / FAQ
Who is mapbox-maplibre-migration for?
Frontend-focused solo builders and tiny teams maintaining MapLibre GL JS who are moving to Mapbox GL JS for support, Studio, and premium global tiles.
When should I use mapbox-maplibre-migration?
During Build frontend work when you are swapping dependencies, adding a Mapbox access token, and retargeting styles before ship or a major map feature release.
Is mapbox-maplibre-migration safe to install?
The skill is read-only guidance; you still expose Mapbox tokens in client code per Mapbox norms—review the Security Audits panel on this page and rotate tokens if the repo is public.
SKILL.md
READMESKILL.md - 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 | 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`