Von Mapbox GL JS zu MapLibre GL JS

MapLibre GL JS entstand im Dezember 2020 als Fork von Mapbox GL JS 1.13, als Mapbox die Version 2 unter eine proprietäre Lizenz stellte. Die API ist ähnlich geblieben; die meisten Karten ziehen also mit wenigen geänderten Zeilen um. Was sich ändert, was es in MapLibre nicht gibt, und was mit Stilen und Kacheln zu tun ist. Getestet mit MapLibre GL JS 6.13.0.

- import mapboxgl from "mapbox-gl";
- import "mapbox-gl/dist/mapbox-gl.css";
- mapboxgl.accessToken = "pk.…";
+ import * as maplibregl from "maplibre-gl";
+ import "maplibre-gl/dist/maplibre-gl.css";

- const map = new mapboxgl.Map({
+ const map = new maplibregl.Map({
    container: "map",
-   style: "mapbox://styles/mapbox/streets-v12",
+   style: "https://api.overpass.ch/v1/IHR_SCHLÜSSEL/maps/styles/light.json",
    center: [8.54, 47.37],
    zoom: 12
  });

1. Das Paket ersetzen

npm uninstall mapbox-gl @types/mapbox-gl
npm install maplibre-gl

MapLibre bringt eigene TypeScript-Typen mit. MapLibre 6 gibt es nur noch als ES-Module; der Default-Import von Mapbox (import mapboxgl from "mapbox-gl") wird also zu einem Namespace-Import oder zu benannten Importen:

import * as maplibregl from "maplibre-gl";
// oder
import { Map, NavigationControl, Marker, Popup } from "maplibre-gl";

Ohne Bundler laden Sie das Modul von einem CDN. Ein klassisches Tag <script src> funktioniert mit Version 6 nicht mehr:

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@6.13.0/dist/maplibre-gl.css">
<script type="module">
import * as maplibregl from "https://unpkg.com/maplibre-gl@6.13.0/dist/maplibre-gl.mjs";
// Ihr Kartencode
</script>

Legen Sie die Version in CDN-URLs fest. Code, der ein klassisches Script-Tag behalten muss, kann MapLibre 5 verwenden, die letzte Version mit diesem Build (maplibre-gl@5.24.0/dist/maplibre-gl.js, global maplibregl).

2. Mit einem Bundler: die Worker-URL setzen

MapLibre liest Kacheln in einem Web Worker. Mit einem Bundler findet MapLibre 6 die Worker-Datei nicht selbst, und die Karte bleibt leer, mit diesem Fehler in der Konsole:

Error: Worker failed to load. Check that the worker URL is correct.

Setzen Sie die URL einmal, vor der ersten Karte. Für Vite, wie wir mit Vite 8 getestet haben:

import { setWorkerUrl } from "maplibre-gl";
import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url";

setWorkerUrl(workerUrl);

Für webpack 5, rspack und Next.js nennt die Dokumentation von MapLibre setWorkerUrl(new URL("maplibre-gl/dist/maplibre-gl-worker.mjs", import.meta.url).toString()). Das CDN-Modul oben braucht keinen Aufruf.

3. Umbenennen und entfernen

• Aus mapboxgl. wird maplibregl.: Map, Marker, Popup, NavigationControl, GeolocateControl, ScaleControl, FullscreenControl und LngLatBounds behalten ihre Namen und Optionen.
• Löschen Sie mapboxgl.accessToken und die Option accessToken. Der Schlüssel Ihres Kachelanbieters kommt stattdessen in die Stil-URL.
• CSS-Klassen beginnen mit maplibregl-: Benennen Sie .mapboxgl-popup, .mapboxgl-marker, .mapboxgl-ctrl und die anderen in Ihren eigenen Stylesheets um.
• Events, addSource, addLayer, Ausdrücke, setPaintProperty, queryRenderedFeatures, fitBounds, flyTo und transformRequest funktionieren wie bisher.
• MapLibre 6 braucht WebGL 2, das aktuelle Browser haben.

Dieser MapLibre-Code lief nach dem Umbenennen oben unverändert: ein Marker mit Popup, ein GeoJSON-Layer mit Klick-Handler und der Globus.

const map = new maplibregl.Map({
  container: "map",
  style: "https://api.overpass.ch/v1/IHR_SCHLÜSSEL/maps/styles/light.json",
  center: [8.54, 47.37],
  zoom: 12
});
map.addControl(new maplibregl.NavigationControl());

new maplibregl.Marker({ color: "#d0312d" })
  .setLngLat([8.5417, 47.3769])
  .setPopup(new maplibregl.Popup().setText("Zürich HB"))
  .addTo(map);

map.on("load", () => {
  map.addSource("stops", { type: "geojson", data: "/stops.geojson" });
  map.addLayer({ id: "stops", type: "circle", source: "stops",
    paint: { "circle-radius": 6, "circle-color": "#1f5fbf" } });
  map.on("click", "stops", (e) => {
    new maplibregl.Popup().setLngLat(e.lngLat).setText(e.features[0].properties.name).addTo(map);
  });
  map.setProjection({ type: "globe" }); // Mapbox: projection: "globe"
});

4. Stile und Kacheln

MapLibre löst keine URLs mapbox:// auf, und die Stile und Kacheln von Mapbox gehören zu Ihrem Mapbox-Konto und seinen Bedingungen. Nach dem Umzug brauchen Sie einen Kachelanbieter und einen Stil für seine Kacheln:

• Verwenden Sie eine fertige Stil-URL. Unsere stehen auf der Seite Kartenkacheln: light, dark, white, grayscale, black, und unsere eigenen Stile Outdoor, Marine, Relief und Driving, mit Beschriftung in 41 Sprachen.
• Ein in Mapbox Studio erstellter Stil verwendet die Layer der Kacheln von Mapbox Streets. Andere Kacheln haben andere Layer: unsere folgen dem Protomaps-Schema, andere OpenMapTiles. Bauen Sie das Aussehen auf einem der neuen Stile nach, zum Beispiel in Maputnik, und liefern Sie das JSON von Ihrer Website aus.
• Ihre eigenen GeoJSON- und Vektorkachel-Quellen ziehen unverändert um. Bei Mapbox gehostete Tilesets (mapbox://username.tileset) brauchen ein neues Zuhause, etwa eine PMTiles-Datei auf Ihrem eigenen Speicher.

5. Gelände, Himmel und Globus

// Mapbox
map.addSource("mapbox-dem", { type: "raster-dem", url: "mapbox://mapbox.mapbox-terrain-dem-v1" });
map.setTerrain({ source: "mapbox-dem", exaggeration: 1.5 });
map.setFog({});

// MapLibre
map.addSource("terrain", { type: "raster-dem", url: "https://api.overpass.ch/v1/IHR_SCHLÜSSEL/maps/terrain.json" });
map.setTerrain({ source: "terrain", exaggeration: 1.5 });
map.setSky({ "sky-color": "#7fb2e5", "horizon-color": "#dfeaf5", "fog-color": "#ffffff" });

Unsere Geländekacheln verwenden die Kodierung Mapbox Terrain-RGB, den Standard von MapLibre. setFog hat kein Gegenstück; setSky setzt die Farben von Himmel, Horizont und Nebel mit anderen Eigenschaftsnamen. Mehr in der Anleitung 3D-Gelände in MapLibre.

6. Funktionen von Mapbox ohne Gegenstück

Diese Funktionen von Mapbox GL JS 2 und 3 gibt es in MapLibre nicht. Jede braucht anderen Code oder eine Entscheidung zur Gestaltung:

7. Plugins

mapbox-gl-draw 1.5.2 lief in unserem Test auf MapLibre 6.13.0, mit seinen Schaltflächen, Polygonen und Modi, nach diesen Zeilen vor new MapboxDraw():

MapboxDraw.constants.classes.CANVAS = "maplibregl-canvas";
MapboxDraw.constants.classes.CONTROL_BASE = "maplibregl-ctrl";
MapboxDraw.constants.classes.CONTROL_PREFIX = "maplibregl-ctrl-";
MapboxDraw.constants.classes.CONTROL_GROUP = "maplibregl-ctrl-group";
MapboxDraw.constants.classes.ATTRIBUTION = "maplibregl-ctrl-attrib";

8. Quellenangabe und Abrechnung

• Das Logo und die Quellenangabe von Mapbox fallen weg, die Quellenangabe der neuen Daten bleibt. Unsere Stile fügen die Quellenangabe von OpenStreetMap selbst ins Attribution-Control ein; lassen Sie sie sichtbar.
• Mapbox GL JS wird pro Kartenaufruf abgerechnet. MapLibre hat keine eigene Abrechnung; Ihr Kachelanbieter rechnet Kacheln ab. overpass.ch zählt jede Kachel einmal, und jedes Konto enthält 100'000 Kacheln im Monat. Was das bei Ihrem Verkehr bedeutet, steht in Preise von Kartenkachel-APIs im Vergleich.

Checkliste

1. Paket, Importe und CSS-Datei tauschen; das Access-Token löschen.
2. Mit einem Bundler einmal setWorkerUrl aufrufen.
3. Klassen .mapboxgl- in Ihrem CSS umbenennen.
4. Jede URL mapbox:// ersetzen: Stil, Gelände, Tilesets, Sprites und Schriften.
5. Optionen des Stils Standard, slot, setFog und die Interactions API ersetzen, falls Sie sie verwenden.
6. Die Plugins tauschen.
7. Die Quellenangabe in der Ecke der Karte prüfen.