Migrate from Mapbox GL JS

MapLibre GL JS began as a fork of Mapbox GL JS v1, so the API is almost identical. Moving a map that uses Mapbox GL JS with the Mapbox tile server over to MapLibre GL JS with the Maptoolkit community tiles is mostly a dependency swap plus a new style URL - and you drop the access token entirely.

1. Swap the dependency

CDN

<!-- Before: Mapbox GL JS -->
<script src="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css" rel="stylesheet" />

<!-- After: MapLibre GL JS -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/maplibre-gl.js"></script>
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/maplibre-gl.css" rel="stylesheet" />

npm

npm uninstall mapbox-gl
npm install maplibre-gl

// Before
import mapboxgl from 'mapbox-gl';
// After
import maplibregl from 'maplibre-gl';

2. Update the map code

Rename the mapboxgl namespace to maplibregl, remove the access token, and point style at the Maptoolkit community style URL.

// Before
mapboxgl.accessToken = 'pk.your-mapbox-token';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [13.405, 52.52],
  zoom: 11,
});

// After
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://styles.maptoolkit.org/summer.json',
  center: [13.405, 52.52],
  zoom: 11,
});

Markers, popups, sources, layers, expressions, and events keep the same names and signatures - new maplibregl.Marker(), map.addSource(), map.addLayer(), map.on('click', …) all work unchanged.

3. Things to check

• No access token. Delete mapboxgl.accessToken; the community tiles need no key.
• Style URL. Replace any mapbox:// style or sprite/glyph URLs with the Maptoolkit style URL.
• Mapbox-only features. APIs that exist only in newer proprietary Mapbox GL JS (v2+) - such as the standard 3D style or Mapbox-hosted datasets - have no MapLibre equivalent and must be rebuilt with MapLibre features.

Attribution

Every map must show the Maptoolkit logo and the © Maptoolkit © OSM copyright line. See Quick Start - Add attribution.