Compétence de Migration MapLibre vers Mapbox

Guidance expert pour migrer de MapLibre GL JS vers Mapbox GL JS. Couvre l'historique partagé, la compatibilité des API, les étapes de migration et les avantages de la plateforme Mapbox.

Comprendre le fork

Historique

MapLibre GL JS est un fork open-source de Mapbox GL JS v1.13.0, créé en décembre 2020 quand Mapbox a changé sa licence à partir de la v2.0.

Chronologie :

• Avant 2020 : Mapbox GL JS était open source (licence BSD)
• Déc 2020 : Mapbox GL JS v2.0 introduit une licence propriétaire
• Déc 2020 : La communauté fork la v1.13 comme MapLibre GL JS
• Aujourd'hui : Les deux bibliothèques continuent leur développement actif

Insight clé : Les API sont ~95% identiques parce que MapLibre a commencé comme un fork de Mapbox. La plupart du code fonctionne dans les deux avec des changements minimes, rendant la migration simple.

Pourquoi migrer vers Mapbox ?

Raisons convaincantes de choisir Mapbox GL JS :

• Support officiel & SLA : Support de classe entreprise avec temps de réponse garantis
• Qualité supérieure des tuiles : Tuiles vectorielles de classe mondiale avec couverture mondiale et mises à jour fréquentes
• Meilleure imagerie satellite : Imagerie satellite et aérienne haute résolution, à jour
• Écosystème riche : Intégration transparente avec Mapbox Studio, API et services
• Fonctionnalités avancées : Routage conscient du trafic, directions détaillées, datasets premium
• Géocodage & Recherche : Recherche d'adresses et recherche de lieux de classe mondiale
• SDK Navigation : Navigation mobile avec trafic en temps réel
• Pas d'infrastructure de tuiles : Pas besoin d'héberger ou maintenir vos propres serveurs de tuiles
• Mises à jour régulières : Améliorations continues et nouvelles fonctionnalités
• Services professionnels : Accès à l'équipe solutions Mapbox pour les projets complexes

Mapbox offre un tier gratuit généreux : 50 000 chargements de carte/mois, ce qui convient à de nombreuses applications sans frais.

Comparaison rapide

Migration étape par étape

1. Créer un compte Mapbox

1. S'inscrire sur mapbox.com
2. Obtenir votre access token du tableau de bord des comptes
3. Consulter la tarification : le tier gratuit inclut 50 000 chargements de carte/mois
4. Noter votre token (commence par pk. pour les tokens publics)

2. Mettre à jour le package

# Supprimer MapLibre
npm uninstall maplibre-gl

# Installer Mapbox
npm install mapbox-gl

3. Mettre à jour les imports

// Avant (MapLibre)
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

// Après (Mapbox)
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

Ou avec CDN :

<!-- Avant (MapLibre) -->
<script src="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.css" rel="stylesheet" />

<!-- Après (Mapbox) -->
<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" />

4. Ajouter l'access token

// Ajouter ceci avant l'initialisation de la carte
mapboxgl.accessToken = 'pk.your_mapbox_access_token';

Bonnes pratiques de token :

• Utiliser des variables d'environnement : process.env.VITE_MAPBOX_TOKEN ou process.env.NEXT_PUBLIC_MAPBOX_TOKEN
• Ajouter les restrictions d'URL dans le tableau de bord Mapbox pour la sécurité
• Utiliser les tokens publics (pk.*) pour le code côté client
• Ne jamais valider les tokens dans git (ajouter à .env et .gitignore)
• Faire tourner les tokens s'ils sont compromis

Voir la compétence mapbox-token-security pour les guidance complètes de sécurité des tokens.

5. Mettre à jour l'initialisation de la carte

// Avant (MapLibre)
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json', // ou votre style personnalisé
  center: [-122.4194, 37.7749],
  zoom: 12
});

// Après (Mapbox)
mapboxgl.accessToken = 'pk.your_mapbox_access_token';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard', // Style Mapbox
  center: [-122.4194, 37.7749],
  zoom: 12
});

6. Mettre à jour l'URL de style

Mapbox fournit des styles conçus et maintenus professionnellement :

// Styles intégrés Mapbox
style: 'mapbox://styles/mapbox/standard'; // Mapbox Standard (défaut)
style: 'mapbox://styles/mapbox/standard-satellite'; // Mapbox Standard Satellite
style: 'mapbox://styles/mapbox/streets-v12'; // Streets v12
style: 'mapbox://styles/mapbox/satellite-v9'; // Imagerie satellite
style: 'mapbox://styles/mapbox/satellite-streets-v12'; // Hybride
style: 'mapbox://styles/mapbox/outdoors-v12'; // Plein air/loisirs
style: 'mapbox://styles/mapbox/light-v11'; // Thème clair
style: 'mapbox://styles/mapbox/dark-v11'; // Thème sombre
style: 'mapbox://styles/mapbox/navigation-day-v1'; // Navigation (jour)
style: 'mapbox://styles/mapbox/navigation-night-v1'; // Navigation (nuit)

Styles personnalisés : Vous pouvez aussi créer et utiliser des styles personnalisés depuis Mapbox Studio :

style: 'mapbox://styles/your-username/your-style-id';

7. Mettre à jour toutes les références

Remplacer toutes les références maplibregl par mapboxgl :

// Marqueurs
const marker = new mapboxgl.Marker() // était : maplibregl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setText('San Francisco'))
  .addTo(map);

// Contrôles
map.addControl(new mapboxgl.NavigationControl(), 'top-right');
map.addControl(new mapboxgl.GeolocateControl());
map.addControl(new mapboxgl.FullscreenControl());
map.addControl(new mapboxgl.ScaleControl());

8. Mettre à jour les plugins (si utilisés)

Certains plugins MapLibre doivent être remplacés par des versions Mapbox :

Exemple :

// Avant (MapLibre)
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

// Après (Mapbox)
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

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

9. Tout le reste reste identique

Tout votre code de carte, événements, couches et sources fonctionnent identiquement :

// Ce code fonctionne EXACTEMENT PAREIL dans les deux bibliothèques
map.on('load', () => {
  map.addSource('points', {
    type: 'geojson',
    data: geojsonData
  });

  map.addLayer({
    id: 'points-layer',
    type: 'circle',
    source: 'points',
    paint: {
      'circle-radius': 8,
      'circle-color': '#ff0000'
    }
  });
});

// Les événements fonctionnent identiquement
map.on('click', 'points-layer', (e) => {
  console.log(e.features[0].properties);
});

// Toutes les méthodes de carte fonctionnent pareil
map.setCenter([lng, lat]);
map.setZoom(12);
map.fitBounds(bounds);
map.flyTo({ center: [lng, lat], zoom: 14 });

Ce qui change : Résumé

Doit changer :

• Nom du package (maplibre-gl -> mapbox-gl)
• Instructions d'import
• Ajouter la configuration mapboxgl.accessToken
• URL de style (passer aux styles mapbox://)
• Packages de plugins (si utilisés)

Reste exactement identique :

• Toutes les méthodes de carte (setCenter, setZoom, fitBounds, flyTo, etc.)
• Tout traitement des événements (map.on('click'), map.on('load'), etc.)
• API Marker/Popup (100% compatible)
• API Layer/source (100% compatible)
• Gestion GeoJSON
• Styles personnalisés et expressions
• Contrôles (Navigation, Geolocate, Scale, etc.)

Problèmes courants de migration

Problème 1 : Token non défini

Problème :

// Erreur : "A valid Mapbox access token is required to use Mapbox GL"
const map = new mapboxgl.Map({...});

Solution :

// Définir le token AVANT de créer la carte
mapboxgl.accessToken = 'pk.your_token';
const map = new mapboxgl.Map({...});

Problème 2 : Token dans Git

Problème :

// Token codé en dur dans le source
mapboxgl.accessToken = 'pk.eyJ1Ijoi...';

Solution :

// Utiliser les variables d'environnement
mapboxgl.accessToken = process.env.VITE_MAPBOX_TOKEN;

// Ajouter au fichier .env (non validé dans git)
VITE_MAPBOX_TOKEN=pk.your_token

// Ajouter .env à .gitignore
echo ".env" >> .gitignore

Problème 3 : Mauvais format d'URL de style

Problème :

// L'URL de style MapLibre ne fonctionnera pas de manière optimale
style: 'https://demotiles.maplibre.org/style.json';

Solution :

// Utiliser l'URL de style Mapbox pour une meilleure performance et des fonctionnalités
style: 'mapbox://styles/mapbox/streets-v12';

Problème 4 : Compatibilité des plugins

Problème :

// Le plugin MapLibre ne fonctionnera pas
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

Solution :

// Utiliser le plugin Mapbox
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

Important : Ceci s'applique à TOUS les plugins MapLibre, pas seulement le géocodeur. Tout plugin @maplibre/* ou maplibre-gl-* doit être remplacé par son équivalent Mapbox. Consulter l'écosystème Mapbox pour les versions spécifiques à Mapbox de chaque plugin que vous utilisez (voir l'étape 8 ci-dessus pour la table de mappage complète).

Problème 5 : URL CDN

Problème :

// CDN incorrect
<script src="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js"></script>

Solution :

// Utiliser le CDN Mapbox
<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' />

Checklist de migration

• [ ] Créer un compte Mapbox et obtenir l'access token
• [ ] Mettre à jour le package : npm install mapbox-gl (supprimer maplibre-gl)
• [ ] Mettre à jour les imports : maplibre-gl -> mapbox-gl
• [ ] Mettre à jour les imports CSS : maplibre-gl.css -> mapbox-gl.css
• [ ] Ajouter le token : Définir mapboxgl.accessToken = 'pk.xxx'
• [ ] Utiliser les variables d'environnement : Stocker le token dans .env
• [ ] Mettre à jour l'URL de style : Changer vers mapbox://styles/mapbox/streets-v12
• [ ] Mettre à jour toutes les références : Remplacer maplibregl. par mapboxgl.
• [ ] Mettre à jour les plugins : Installer les versions Mapbox des plugins (si utilisés)
• [ ] Configurer la sécurité des tokens : Ajouter les restrictions d'URL dans le tableau de bord
• [ ] Tester toutes les fonctionnalités : Vérifier que la carte se charge et les interactions fonctionnent
• [ ] Configurer les alertes de facturation : Surveiller l'utilisation dans le tableau de bord Mapbox
• [ ] Mettre à jour la documentation : Documenter la configuration du token pour l'équipe
• [ ] Ajouter .env à .gitignore : Assurer que les tokens ne sont pas validés

Référence rapide

Résumé des différences clés

En résumé : La migration est facile parce que les API sont presque identiques. Les changements principaux sont l'empaquetage, la configuration du token et les URL de style. Le résultat est l'accès aux tuiles premium, à l'écosystème et au support de Mapbox.

Intégration avec d'autres compétences

Compétences associées :

• mapbox-web-integration-patterns : Patterns spécifiques aux frameworks (React, Vue, Svelte, Angular)
• mapbox-web-performance-patterns : Techniques d'optimisation des performances
• mapbox-token-security : Bonnes pratiques complètes de sécurité des tokens
• mapbox-google-maps-migration : Migrer de Google Maps vers Mapbox

Ressources

Mapbox GL JS :

• Documentation officielle
• Galerie d'exemples
• Référence API
• Dépôt GitHub
• Mapbox Studio
• Informations de tarification

Support de migration :

• Guide de démarrage
• Spécification de style
• Support communautaire Mapbox

Fichiers de référence

Pour des informations détaillées sur des sujets spécifiques, charger ces fichiers de référence :

• references/api-compatibility.md -- Liste complète des API 100% compatibles + exemple de migration côte à côte
• references/exclusive-features.md -- Fonctionnalités exclusives à Mapbox (API, Studio, Advanced) + exemples des frameworks React/Vue
• references/why-mapbox.md -- Pourquoi choisir Mapbox (Production, Équipes dev, Business) + Comparaison des performances