maplibre-mapbox-migration
installsforks
How to install maplibre-mapbox-migration?
maplibre/maplibre-agent-skills/maplibre-mapbox-migration
$npx -y skills add maplibre/maplibre-agent-skills --skill maplibre-mapbox-migrationMigrating from Mapbox GL JS to MapLibre GL JS — package and import changes, removing the access token, choosing tile sources, plugin equivalents, and what you gain or give up. Use when moving an existing Mapbox map to MapLibre.
SKILL.md
| 1 | # Mapbox to MapLibre Migration |
| 2 | |
| 3 | This skill guides you through migrating an application from **Mapbox GL JS** to **MapLibre GL JS**. The two libraries share a common ancestry (MapLibre forked from Mapbox GL JS v1.13 in December 2020), so the API is largely the same. The main changes are: swap the package, replace the namespace, remove the Mapbox access token, and **choose a new tile source** (MapLibre does not use `mapbox://` styles). |
| 4 | |
| 5 | **Primary reference:** [MapLibre official Mapbox migration guide](https://maplibre.org/maplibre-gl-js/docs/guides/mapbox-migration-guide/). |
| 6 | |
| 7 | ## When to Use This Skill |
| 8 | |
| 9 | - Migrating an existing Mapbox GL JS app to MapLibre |
| 10 | - Evaluating MapLibre as an open-source alternative to Mapbox |
| 11 | - Understanding API compatibility and what breaks |
| 12 | - Choosing tile sources and services after moving off Mapbox |
| 13 | |
| 14 | ## Why Migrate to MapLibre? |
| 15 | |
| 16 | Common reasons teams switch from Mapbox to MapLibre: |
| 17 | |
| 18 | - **Open-source license** — MapLibre is BSD-3-Clause; no vendor lock-in or proprietary terms |
| 19 | - **No access token** — The library does not require a Mapbox token; tile sources may have their own keys or none (e.g. OpenFreeMap) |
| 20 | - **Cost** — Avoid Mapbox map-load and API pricing; use free or fixed-cost tile and geocoding providers |
| 21 | - **Self-hosting** — Use your own tiles (PMTiles, tileserver-gl, Martin) or any third-party source |
| 22 | - **Community** — MapLibre is maintained by the MapLibre organization and community; style spec and APIs evolve in the open |
| 23 | - **Community-supported funding** — MapLibre is funded by donations from many companies and individuals; there is no single commercial backer, so the project stays aligned with the community |
| 24 | - **Open vector tile format (MLT)** — MapLibre offers [MapLibre Tile (MLT)](https://maplibre.org/maplibre-tile-spec/), a modern alternative to Mapbox Vector Tiles (MVT) with better compression and support for 3D coordinates and elevation; supported in GL JS and Native, and can be generated with Planetiler |
| 25 | |
| 26 | **What you give up:** Mapbox Studio integration, Mapbox-hosted tiles and styles, Mapbox Search/Directions/Geocoding APIs, official Mapbox support. |
| 27 | |
| 28 | ## Understanding the Fork |
| 29 | |
| 30 | - **Dec 2020:** Mapbox GL JS v2.0 switched to a proprietary license. The community forked v1.13 as **MapLibre GL JS**. [MapLibre organization](https://github.com/maplibre) and [GL JS repo](https://github.com/maplibre/maplibre-gl-js) are the canonical homes. |
| 31 | - **API:** MapLibre GL JS v1.x is largely backward compatible with Mapbox GL JS v1.x. Most map code (methods, events, layers, sources) works with minimal changes. |
| 32 | - **Releases since the fork:** MapLibre has moved ahead with its own version line. v2/v3 brought WebGL2, a modern renderer, and features like hillshade and terrain; v4 introduced Promises in public APIs (replacing many callbacks); v5 added globe view and the [Adaptive Composite Map Projection](https://maplibre.org/maplibre-gl-js/docs/API/). See [releases](https://github.com/maplibre/maplibre-gl-js/releases) and [CHANGELOG](https://github.com/maplibre/maplibre-gl-js/blob/main/CHANGELOG.md). |
| 33 | - **Style spec:** MapLibre maintains its own [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/) (forked from the Mapbox spec). It is compatible for most styles but has added and diverged in places; check the [style spec site](https://maplibre.org/maplibre-style-spec/) when using newer or MapLibre-specific features. |
| 34 | - **Ecosystem:** Besides GL JS, the MapLibre org hosts [MapLibre Native](https://maplibre.org/projects/native/) (iOS, Android, desktop), [Martin](https://maplibre.org/martin/) (vector tile server from PostGIS/PMTiles/MBTiles), and the [MapLibre Tile (MLT)](https://maplibre.org/maplibre-tile-spec/) format. Roadmaps and news: [maplibre.org/roadmap](https://maplibre.org/roadmap/), [maplibre.org/news](https://maplibre.org/news/). |
| 35 | |
| 36 | ## Step-by-Step Migration |
| 37 | |
| 38 | ### 1. Install the Package |
| 39 | |
| 40 | ```bash |
| 41 | npm install maplibre-gl |
| 42 | ``` |
| 43 | |
| 44 | ### 2. Update Imports and CSS |
| 45 | |
| 46 | ```javascript |
| 47 | // Before (Mapbox) |
| 48 | import mapboxgl from 'mapbox-gl'; |
| 49 | import 'mapbox-gl/dist/mapbox-gl.css'; |
| 50 | |
| 51 | // After (MapLibre) |
| 52 | import maplibregl from 'maplibre-gl'; |
| 53 | import 'maplibre-gl/dist/maplibre-gl.css'; |
| 54 | ``` |
| 55 | |
| 56 | **CDN:** Replace Mapbox script/link with MapLibre: |
| 57 | |
| 58 | - Script: `https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.js` → `https://unpkg.com/maplibre-gl@*.*.*/dist/maplibre-gl.js` |
| 59 | - CSS: same pattern (mapbox-gl.css → maplibre-gl.css). |
| 60 | |
| 61 | ### 3. Replace the Namespace |
| 62 | |
| 63 | Replace all `mapboxgl` with `maplibregl` (and `mapbox-gl` with `maplibre-gl` in package names or paths). Examples: |
| 64 | |
| 65 | ```javascript |
| 66 | // Before (Mapbox) |
| 67 | const map = new mapboxgl.Map({ ... }); |
| 68 | new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map); |
| 69 | map.addControl(new mapboxgl.NavigationCon |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
