Update to Mapbox

{
  "name": "mapbox-maplibre-migration",
  "description": "Guide for migrating from MapLibre GL JS to Mapbox GL JS, covering API compatibility, token setup, style configuration, and the benefits of Mapbox's official support and ecosystem",
  "included_files": [
    {
      "relative_path": "AGENTS.md",
      "size_in_bytes": 8268
    },
    {
      "relative_path": "evals/evals.json",
      "size_in_bytes": 2182
    },
    {
      "relative_path": "references/api-compatibility.md",
      "size_in_bytes": 2320
    },
    {
      "relative_path": "references/exclusive-features.md",
      "size_in_bytes": 3174
    },
    {
      "relative_path": "references/why-mapbox.md",
      "size_in_bytes": 2353
    }
  ],
  "skill_md_contents": "---\nname: mapbox-maplibre-migration\ndescription: Guide for migrating from MapLibre GL JS to Mapbox GL JS, covering API compatibility, token setup, style configuration, and the benefits of Mapbox's official support and ecosystem\n---\n\n# MapLibre to Mapbox Migration Skill\n\nExpert guidance for migrating from MapLibre GL JS to Mapbox GL JS. Covers the shared history, API compatibility, migration steps, and the advantages of Mapbox's platform.\n\n## Understanding the Fork\n\n### History\n\n**MapLibre GL JS** is an open-source fork of **Mapbox GL JS v1.13.0**, created in December 2020 when Mapbox changed their license starting with v2.0.\n\n**Timeline:**\n\n- **Pre-2020:** Mapbox GL JS was open source (BSD license)\n- **Dec 2020:** Mapbox GL JS v2.0 introduced proprietary license\n- **Dec 2020:** Community forked v1.13 as MapLibre GL JS\n- **Present:** Both libraries continue active development\n\n**Key Insight:** The APIs are ~95% identical because MapLibre started as a Mapbox fork. Most code works in both with minimal changes, making migration straightforward.\n\n## Why Migrate to Mapbox?\n\n**Compelling reasons to choose Mapbox GL JS:**\n\n- **Official Support & SLAs**: Enterprise-grade support with guaranteed response times\n- **Superior Tile Quality**: Best-in-class vector tiles with global coverage and frequent updates\n- **Better Satellite Imagery**: High-resolution, up-to-date satellite and aerial imagery\n- **Rich Ecosystem**: Seamless integration with Mapbox Studio, APIs, and services\n- **Advanced Features**: Traffic-aware routing, turn-by-turn directions, premium datasets\n- **Geocoding & Search**: World-class address search and place lookup\n- **Navigation SDK**: Mobile navigation with real-time traffic\n- **No Tile Infrastructure**: No need to host or maintain your own tile servers\n- **Regular Updates**: Continuous improvements and new features\n- **Professional Services**: Access to Mapbox solutions team for complex projects\n\n**Mapbox offers a generous free tier:** 50,000 map loads/month, making it suitable for many applications without cost.\n\n## Quick Comparison\n\n| Aspect                | Mapbox GL JS                  | MapLibre GL JS                    |\n| --------------------- | ----------------------------- | --------------------------------- |\n| **License**           | Proprietary (v2+)             | BSD 3-Clause (Open Source)        |\n| **Support**           | Official commercial support   | Community support                 |\n| **Tiles**             | Premium Mapbox vector tiles   | OSM or custom tile sources        |\n| **Satellite**         | High-quality global imagery   | Requires custom source            |\n| **Token**             | Required (access token)       | Optional (depends on tile source) |\n| **APIs**              | Full Mapbox ecosystem         | Requires third-party services     |\n| **Studio**            | Full integration              | No native integration             |\n| **3D Terrain**        | Built-in with premium data    | Available (requires data source)  |\n| **Globe View**        | v2.9+                         | v3.0+                             |\n| **API Compatibility** | ~95% compatible with MapLibre | ~95% compatible with Mapbox       |\n| **Bundle Size**       | ~500KB                        | ~450KB                            |\n| **Setup Complexity**  | Easy (just add token)         | Requires tile source setup        |\n\n## Step-by-Step Migration\n\n### 1. Create Mapbox Account\n\n1. Sign up at [mapbox.com](https://mapbox.com)\n2. Get your access token from the account dashboard\n3. Review pricing: Free tier includes 50,000 map loads/month\n4. Note your token (starts with `pk.` for public tokens)\n\n### 2. Update Package\n\n```bash\n# Remove MapLibre\nnpm uninstall maplibre-gl\n\n# Install Mapbox\nnpm install mapbox-gl\n```\n\n### 3. Update Imports\n\n```javascript\n// Before (MapLibre)\nimport maplibregl from 'maplibre-gl';\nimport 'maplibre-gl/dist/maplibre-gl.css';\n\n// After (Mapbox)\nimport mapboxgl from 'mapbox-gl';\nimport 'mapbox-gl/dist/mapbox-gl.css';\n```\n\nOr with CDN:\n\n```html\n<!-- Before (MapLibre) -->\n<script src=\"https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js\"></script>\n<link href=\"https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.css\" rel=\"stylesheet\" />\n\n<!-- After (Mapbox) -->\n<script src=\"https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js\"></script>\n<link href=\"https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css\" rel=\"stylesheet\" />\n```\n\n### 4. Add Access Token\n\n```javascript\n// Add this before map initialization\nmapboxgl.accessToken = 'pk.your_mapbox_access_token';\n```\n\n**Token best practices:**\n\n- Use environment variables: `process.env.VITE_MAPBOX_TOKEN` or `process.env.NEXT_PUBLIC_MAPBOX_TOKEN`\n- Add URL restrictions in Mapbox dashboard for security\n- Use public tokens (`pk.*`) for client-side code\n- Never commit tokens to git (add to `.env` and `.gitignore`)\n- Rotate tokens if compromised\n\nSee `mapbox-token-security` skill for comprehensive token security guidance.\n\n### 5. Update Map Initialization\n\n```javascript\n// Before (MapLibre)\nconst map = new maplibregl.Map({\n  container: 'map',\n  style: 'https://demotiles.maplibre.org/style.json', // or your custom style\n  center: [-122.4194, 37.7749],\n  zoom: 12\n});\n\n// After (Mapbox)\nmapboxgl.accessToken = 'pk.your_mapbox_access_token';\n\nconst map = new mapboxgl.Map({\n  container: 'map',\n  style: 'mapbox://styles/mapbox/standard', // Mapbox style\n  center: [-122.4194, 37.7749],\n  zoom: 12\n});\n```\n\n### 6. Update Style URL\n\nMapbox provides professionally designed, maintained styles:\n\n```javascript\n// Mapbox built-in styles\nstyle: 'mapbox://styles/mapbox/standard'; // Mapbox Standard (default)\nstyle: 'mapbox://styles/mapbox/standard-satellite'; // Mapbox Standard Satellite\nstyle: 'mapbox://styles/mapbox/streets-v12'; // Streets v12\nstyle: 'mapbox://styles/mapbox/satellite-v9'; // Satellite imagery\nstyle: 'mapbox://styles/mapbox/satellite-streets-v12'; // Hybrid\nstyle: 'mapbox://styles/mapbox/outdoors-v12'; // Outdoor/recreation\nstyle: 'mapbox://styles/mapbox/light-v11'; // Light theme\nstyle: 'mapbox://styles/mapbox/dark-v11'; // Dark theme\nstyle: 'mapbox://styles/mapbox/navigation-day-v1'; // Navigation (day)\nstyle: 'mapbox://styles/mapbox/navigation-night-v1'; // Navigation (night)\n```\n\n**Custom styles:**\nYou can also create and use custom styles from Mapbox Studio:\n\n```javascript\nstyle: 'mapbox://styles/your-username/your-style-id';\n```\n\n### 7. Update All References\n\nReplace all `maplibregl` references with `mapboxgl`:\n\n```javascript\n// Markers\nconst marker = new mapboxgl.Marker() // was: maplibregl.Marker()\n  .setLngLat([-122.4194, 37.7749])\n  .setPopup(new mapboxgl.Popup().setText('San Francisco'))\n  .addTo(map);\n\n// Controls\nmap.addControl(new mapboxgl.NavigationControl(), 'top-right');\nmap.addControl(new mapboxgl.GeolocateControl());\nmap.addControl(new mapboxgl.FullscreenControl());\nmap.addControl(new mapboxgl.ScaleControl());\n```\n\n### 8. Update Plugins (If Used)\n\nSome MapLibre plugins should be replaced with Mapbox versions:\n\n| MapLibre Plugin                  | Mapbox Alternative           |\n| -------------------------------- | ---------------------------- |\n| `@maplibre/maplibre-gl-geocoder` | `@mapbox/mapbox-gl-geocoder` |\n| `@maplibre/maplibre-gl-draw`     | `@mapbox/mapbox-gl-draw`     |\n| `maplibre-gl-compare`            | `mapbox-gl-compare`          |\n\nExample:\n\n```javascript\n// Before (MapLibre)\nimport MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';\n\n// After (Mapbox)\nimport MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';\n\nmap.addControl(\n  new MapboxGeocoder({\n    accessToken: mapboxgl.accessToken,\n    mapboxgl: mapboxgl,\n    countries: 'us', // ISO 3166-1 alpha-2 code(s), comma-separated; hard filter, not a soft bias\n    language: 'en' // Also affects which result ranks first, not just the UI/response text\n  })\n);\n```\n\n**Note:** `countries` and `language` change _which_ results come back, not just how they're filtered or displayed. `language` affects result scoring (the same query can rank a different place first depending on language), and `countries` excludes everything outside the listed codes. Carry over any locale/region restrictions from the original MapLibre geocoder.\n\n### 9. Everything Else Stays the Same\n\nAll your map code, events, layers, and sources work identically:\n\n```javascript\n// This code works EXACTLY THE SAME in both libraries\nmap.on('load', () => {\n  map.addSource('points', {\n    type: 'geojson',\n    data: geojsonData\n  });\n\n  map.addLayer({\n    id: 'points-layer',\n    type: 'circle',\n    source: 'points',\n    paint: {\n      'circle-radius': 8,\n      'circle-color': '#ff0000'\n    }\n  });\n});\n\n// Events work identically\nmap.on('click', 'points-layer', (e) => {\n  console.log(e.features[0].properties);\n});\n\n// All map methods work the same\nmap.setCenter([lng, lat]);\nmap.setZoom(12);\nmap.fitBounds(bounds);\nmap.flyTo({ center: [lng, lat], zoom: 14 });\n```\n\n## What Changes: Summary\n\n**Must change:**\n\n- Package name (`maplibre-gl` -> `mapbox-gl`)\n- Import statements\n- Add `mapboxgl.accessToken` configuration\n- Style URL (switch to `mapbox://` styles)\n- Plugin packages (if used)\n\n**Stays exactly the same:**\n\n- All map methods (`setCenter`, `setZoom`, `fitBounds`, `flyTo`, etc.)\n- All event handling (`map.on('click')`, `map.on('load')`, etc.)\n- Marker/Popup APIs (100% compatible)\n- Layer/source APIs (100% compatible)\n- GeoJSON handling\n- Custom styling and expressions\n- Controls (Navigation, Geolocate, Scale, etc.)\n\n## Common Migration Issues\n\n### Issue 1: Token Not Set\n\n**Problem:**\n\n```javascript\n// Error: \"A valid Mapbox access token is required to use Mapbox GL\"\nconst map = new mapboxgl.Map({...});\n```\n\n**Solution:**\n\n```javascript\n// Set token BEFORE creating map\nmapboxgl.accessToken = 'pk.your_token';\nconst map = new mapboxgl.Map({...});\n```\n\n### Issue 2: Token in Git\n\n**Problem:**\n\n```javascript\n// Token hardcoded in source\nmapboxgl.accessToken = 'pk.eyJ1Ijoi...';\n```\n\n**Solution:**\n\n```javascript\n// Use environment variables\nmapboxgl.accessToken = process.env.VITE_MAPBOX_TOKEN;\n\n// Add to .env file (not committed to git)\nVITE_MAPBOX_TOKEN=pk.your_token\n\n// Add .env to .gitignore\necho \".env\" >> .gitignore\n```\n\n### Issue 3: Wrong Style URL Format\n\n**Problem:**\n\n```javascript\n// MapLibre-style URL won't work optimally\nstyle: 'https://demotiles.maplibre.org/style.json';\n```\n\n**Solution:**\n\n```javascript\n// Use Mapbox style URL for better performance and features\nstyle: 'mapbox://styles/mapbox/streets-v12';\n```\n\n### Issue 4: Plugin Compatibility\n\n**Problem:**\n\n```javascript\n// MapLibre plugin won't work\nimport MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';\n```\n\n**Solution:**\n\n```javascript\n// Use Mapbox plugin\nimport MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';\n```\n\n> **Important:** This applies to ALL MapLibre plugins, not just the geocoder. Any `@maplibre/*` or `maplibre-gl-*` plugin must be replaced with its Mapbox equivalent. Check the Mapbox ecosystem for Mapbox-specific versions of every plugin you use (see Step 8 above for the full mapping table).\n\n### Issue 5: CDN URLs\n\n**Problem:**\n\n```javascript\n// Wrong CDN\n<script src=\"https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js\"></script>\n```\n\n**Solution:**\n\n```javascript\n// Use Mapbox CDN\n<script src='https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js'></script>\n<link href='https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css' rel='stylesheet' />\n```\n\n## Migration Checklist\n\n- [ ] **Create Mapbox account** and get access token\n- [ ] **Update package**: `npm install mapbox-gl` (remove maplibre-gl)\n- [ ] **Update imports**: `maplibre-gl` -> `mapbox-gl`\n- [ ] **Update CSS imports**: `maplibre-gl.css` -> `mapbox-gl.css`\n- [ ] **Add token**: Set `mapboxgl.accessToken = 'pk.xxx'`\n- [ ] **Use environment variables**: Store token in `.env`\n- [ ] **Update style URL**: Change to `mapbox://styles/mapbox/streets-v12`\n- [ ] **Update all references**: Replace `maplibregl.` with `mapboxgl.`\n- [ ] **Update plugins**: Install Mapbox versions of plugins (if used)\n- [ ] **Configure token security**: Add URL restrictions in dashboard\n- [ ] **Test all functionality**: Verify map loads, interactions work\n- [ ] **Set up billing alerts**: Monitor usage in Mapbox dashboard\n- [ ] **Update documentation**: Document token setup for team\n- [ ] **Add .env to .gitignore**: Ensure tokens not committed\n\n## Quick Reference\n\n### Key Differences Summary\n\n| What    | MapLibre                               | Mapbox                                      |\n| ------- | -------------------------------------- | ------------------------------------------- |\n| Package | `maplibre-gl`                          | `mapbox-gl`                                 |\n| Import  | `import maplibregl from 'maplibre-gl'` | `import mapboxgl from 'mapbox-gl'`          |\n| Token   | Optional (depends on tiles)            | Required: `mapboxgl.accessToken = 'pk.xxx'` |\n| Style   | Custom URL or OSM tiles                | `mapbox://styles/mapbox/streets-v12`        |\n| License | BSD (Open Source)                      | Proprietary (v2+)                           |\n| Support | Community                              | Official commercial support                 |\n| Tiles   | Requires tile source                   | Premium Mapbox tiles included               |\n| APIs    | Third-party                            | Full Mapbox API ecosystem                   |\n| API     | ~95% compatible                        | ~95% compatible                             |\n\n**Bottom line:** Migration is easy because APIs are nearly identical. Main changes are packaging, token setup, and style URLs. The result is access to Mapbox's premium tiles, ecosystem, and support.\n\n## Integration with Other Skills\n\n**Related skills:**\n\n- **mapbox-web-integration-patterns**: Framework-specific patterns (React, Vue, Svelte, Angular)\n- **mapbox-web-performance-patterns**: Performance optimization techniques\n- **mapbox-token-security**: Comprehensive token security best practices\n- **mapbox-google-maps-migration**: Migrate from Google Maps to Mapbox\n\n## Resources\n\n**Mapbox GL JS:**\n\n- [Official Documentation](https://docs.mapbox.com/mapbox-gl-js/)\n- [Example Gallery](https://docs.mapbox.com/mapbox-gl-js/examples/)\n- [API Reference](https://docs.mapbox.com/mapbox-gl-js/api/)\n- [GitHub Repository](https://github.com/mapbox/mapbox-gl-js)\n- [Mapbox Studio](https://studio.mapbox.com/)\n- [Pricing Information](https://www.mapbox.com/pricing/)\n\n**Migration Support:**\n\n- [Get Started Guide](https://docs.mapbox.com/mapbox-gl-js/guides/install/)\n- [Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/)\n- [Mapbox Community Support](https://support.mapbox.com/hc/en-us/community/topics)\n\n## Reference Files\n\nFor detailed information on specific topics, load these reference files:\n\n- **`references/api-compatibility.md`** -- Full list of 100% compatible APIs + side-by-side migration example\n- **`references/exclusive-features.md`** -- Mapbox-exclusive features (APIs, Studio, Advanced) + React/Vue framework examples\n- **`references/why-mapbox.md`** -- Why Choose Mapbox (Production, Dev Teams, Business) + Performance Comparison\n"
}