mapbox/mapbox-web-integ-patterns

mapbox/mapbox-web-integrationsmuster

Offizielle Integrationsmuster für Mapbox GL JS in gängigen Web-Frameworks (React, Vue, Svelte, Angular). Behandelt Einrichtung, Lebenszyklus-Management, Token-Handhabung, Suchintegration und häufige Fallstricke. Basiert auf Mapboxs create-web-app-Scaffolding-Tool.

Überblick

Dieser Skill stellt bewährte Verfahren für die Integration von Mapbox GL JS in moderne JavaScript-Frameworks bereit. Er deckt die folgenden Bereiche ab:

• Einrichtung: Initialisierung von Mapbox GL JS in jedem Framework
• Lebenszyklus-Management: Korrektes Mounten und Unmounten der Karteninstanz
• Token-Handhabung: Sicherer Umgang mit Mapbox Access-Tokens (Umgebungsvariablen, serverseitige Proxys)
• Suchintegration: Einbindung der Mapbox-Suche (Geocoding) in die Kartenansicht
• Häufige Fallstricke: Vermeidung von Fehlern wie doppelten Karteninstanzen, Token-Leaks und Performance-Problemen

Unterstützte Frameworks

• React (mit useEffect, useRef)
• Vue (Options-API und Composition-API)
• Svelte (mit onMount, onDestroy)
• Angular (mit ngOnInit, ngOnDestroy)

Verwendung

Jedes Beispiel folgt dem gleichen grundlegenden Muster:

1. Installation von Mapbox GL JS (npm install mapbox-gl)
2. Einrichtung eines Access-Tokens (mapboxgl.accessToken = '...')
3. Erstellen einer Karteninstanz in der onMount/useEffect/ngOnInit-Phase
4. Aufräumen der Karte in der onDestroy/useEffect-Cleanup/ngOnDestroy-Phase

Beispiel: React

import { useEffect, useRef } from 'react';
import mapboxgl from 'mapbox-gl';

mapboxgl.accessToken = process.env.REACT_APP_MAPBOX_TOKEN;

export default function Map() {
  const mapContainer = useRef(null);
  const map = useRef(null);

  useEffect(() => {
    if (map.current) return; // Verhindert doppelte Initialisierung

    map.current = new mapboxgl.Map({
      container: mapContainer.current,
      style: 'mapbox://styles/mapbox/streets-v12',
      center: [-74.5, 40],
      zoom: 9
    });

    return () => {
      map.current.remove();
      map.current = null;
    };
  }, []);

  return <div ref={mapContainer} style={{ width: '100%', height: '400px' }} />;
}

Token-Handhabung

Verwenden Sie immer Umgebungsvariablen (z. B. REACT_APP_MAPBOX_TOKEN in React, VITE_MAPBOX_TOKEN in Vue) und speichern Sie Tokens nie im Quellcode. Für zusätzliche Sicherheit kann ein serverseitiger Proxy konfiguriert werden.

Suchintegration (Geocoding)

Verwenden Sie das Mapbox-GL-Geocoder-Plugin:

npm install @mapbox/mapbox-gl-geocoder

Fügen Sie es dann zur Karte hinzu:

import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

map.addControl(
  new MapboxGeocoder({
    accessToken: mapboxgl.accessToken,
    mapboxgl: mapboxgl
  })
);

Häufige Fallstricke

• Doppelte Karten: Stellen Sie sicher, dass die Karte nur einmal initialisiert wird (z. B. mit einem Ref-Check in React).
• Token-Leaks: Setzen Sie Token nie im clientseitigen Code hart; verwenden Sie Umgebungsvariablen.
• Vergessenes Aufräumen: Entfernen Sie die Karte immer beim Unmount, um Speicherlecks zu vermeiden.
• Falsche Container-Dimensionen: Stellen Sie sicher, dass der Kartencontainer eine definierte Höhe hat.

Referenz

Dieser Skill basiert auf der offiziellen Mapbox-Dokumentation und dem create-web-app-Scaffolding-Tool. Weitere Details finden Sie unter mapbox.com.