Intégrer MapLibre GL JS dans une application Angular, du paquet npm au rendu serveur

Ce qui a changé en 2026 pour une carte dans Angular

Le 22 juillet 2026, MapLibre GL JS publie sa version 6.0. Le lecteur qui met à jour un projet existant voit sa compilation tomber sur la première ligne : le paquet n'a plus d'export par défaut. Nous l'avons vérifié le 27 septembre avec TypeScript : import maplibregl from 'maplibre-gl' rend l'erreur TS1192, « has no default export ». La même version abandonne WebGL 1, retire le second paramètre de GeoJSONSource.setData et ne publie plus le fichier UMD qu'on chargeait par une balise <script>.

Côté Angular, le changement date du 19 novembre 2025 : la version 21 rend l'application sans zone par défaut. NgZone.runOutsideAngular reste compatible, la documentation le dit en toutes lettres, mais il ne protège plus rien dans une application neuve. Il reste indispensable dans toutes celles qui tournent encore sous zone.js.

MapLibre elle-même est le fork libre de Mapbox GL JS, né quand Mapbox a changé de licence en décembre 2020. Elle est sous licence BSD à trois clauses. Nos cartes tournent sur un moteur construit au-dessus d'elle, dans une application Angular : les motifs qui suivent sont ceux qui tiennent sous des centaines de milliers de sessions.

La recette en cinq gestes

Le guide de migration de MapLibre 6 le dit sans détour : avec un outil de build, import.meta.url ne retrouve pas le fichier du worker, et chaque projet doit appeler setWorkerUrl() une fois. Angular construit avec esbuild par défaut depuis sa version 17, il est donc concerné. Voici l'ordre qui tient avec les versions de septembre 2026.

1. 1

   Installer le paquet, sa feuille de style et son worker

   npm install maplibre-gl, puis la feuille de style dans styles et le fichier du worker dans assets du fichier angular.json. Sans le worker, la carte reste grise.

2. 2

   Créer la carte après le premier rendu, hors de la zone

   afterNextRender garantit que le conteneur existe dans le DOM et ne s'exécute jamais sur le serveur. runOutsideAngular sort la boucle d'animation de MapLibre de la détection de changement.

3. 3

   Attendre le style avant toute source ou couche

   addSource avant la fin du chargement du style lève une erreur. On écoute style.load, qui se déclenche au premier style et à chaque setStyle.

4. 4

   Laisser un signal piloter les données

   Un effect() lit le signal des données et appelle setData sur la source existante. La carte ne recrée jamais ses couches pour un simple changement de données.

5. 5

   Détruire proprement

   DestroyRef.onDestroy appelle map.remove(), qui libère le DOM, les écouteurs, les workers et le contexte WebGL.

La configuration de build tient en deux entrées : la feuille de style dans styles, le worker copié tel quel à la racine du site.

angular.json, dans build.options

"styles": ["node_modules/maplibre-gl/dist/maplibre-gl.css", "src/styles.css"],
"assets": [
  { "glob": "**/*", "input": "public" },
  { "glob": "maplibre-gl-worker.mjs", "input": "node_modules/maplibre-gl/dist", "output": "/" }
]

Créer la carte après le rendu, hors de la zone Angular

Le piège le plus coûteux ne se voit pas au premier essai. Sous zone.js, chaque écouteur que MapLibre pose sur le canvas, glissé, molette, toucher, et chaque image de sa boucle requestAnimationFrame, déclenche une détection de changement sur toute l'application. Sur une page légère, rien ne se sent. Sur une page avec un panneau de résultats et cent marqueurs, le glissé saccade. On le lit au profileur : des tâches longues à chaque déplacement, sans aucun changement d'état.

La règle : la carte naît hors de la zone, et seuls les gestes qui changent l'état de l'application y reviennent. Le module est importé à la demande, ce qui sort ses 296 Ko compressés du paquet initial.

carte.component.ts, la création

import { Component, DestroyRef, ElementRef, NgZone, afterNextRender, effect, inject, input, output, signal, viewChild } from '@angular/core';
import type { GeoJSONSource, Map as MapLibreMap, Marker } from 'maplibre-gl';
import type { FeatureCollection } from 'geojson';

@Component({
  selector: 'app-carte',
  template: `<div #conteneur class="carte"></div>`,
  styles: `.carte { height: 480px; }`,
})
export class CarteComponent {
  readonly styleUrl = input.required<string>();
  readonly traces = input<FeatureCollection>({ type: 'FeatureCollection', features: [] });

  private readonly conteneur = viewChild.required<ElementRef<HTMLDivElement>>('conteneur');
  private readonly zone = inject(NgZone);
  private readonly carte = signal<MapLibreMap | null>(null);
  private maplibre?: typeof import('maplibre-gl');
  private detruit = false;

  constructor() {
    afterNextRender(async () => {
      const maplibre = await import('maplibre-gl');
      if (this.detruit) return;
      this.maplibre = maplibre;
      maplibre.setWorkerUrl(new URL('maplibre-gl-worker.mjs', document.baseURI).href);

      const map = this.zone.runOutsideAngular(() => new maplibre.Map({
        container: this.conteneur().nativeElement,
        style: this.styleUrl(),
        center: [5.8, 45.35],
        zoom: 10,
      }));
      map.on('style.load', () => this.ajouterCouches(map));
    });
  }
}

La garde detruit n'est pas décorative. Entre le rendu et l'arrivée du module, l'utilisateur peut avoir quitté la page : sans elle, une carte naît dans un composant déjà détruit et personne ne la libère.

Couches et données : attendre le style, puis laisser un signal piloter setData

Avant la version 6, setData(data, true) attendait la fin du traitement dans le worker et renvoyait la source. Le 22 juillet 2026, ce second paramètre a disparu : le même appel ne compile plus, TypeScript répond « Expected 1 arguments, but got 2 ». La méthode rend désormais une promesse.

La règle : une source se crée une fois, à style.load, puis ne reçoit plus que setData. Un effect() sur le signal des données fait le lien. Il se relance quand les données changent, et aussi quand la carte devient prête, ce qui règle l'ordre d'arrivée sans une ligne de RxJS.

carte.component.ts, la source et le signal

private ajouterCouches(map: MapLibreMap) {
  if (!map.getSource('traces')) {
    map.addSource('traces', { type: 'geojson', data: this.traces() });
    map.addLayer({
      id: 'traces-ligne',
      type: 'line',
      source: 'traces',
      layout: { 'line-join': 'round', 'line-cap': 'round' },
      paint: { 'line-color': '#0d1d27', 'line-width': 4 },
    });
  }
  this.carte.set(map);
}

private readonly synchroniser = effect(() => {
  const map = this.carte();
  const data = this.traces();
  (map?.getSource('traces') as GeoJSONSource | undefined)?.setData(data);
});

Marqueurs, taille du conteneur et destruction

Le 23 mai 2023, MapLibre 3.0 a branché un ResizeObserver sur le conteneur de la carte. Avec l'option trackResize à sa valeur par défaut, la carte suit son conteneur, y compris un conteneur masqué en CSS qui réapparaît dans un onglet. Le ResizeObserver écrit à la main et encore recopié de tutoriel en tutoriel appelle donc resize() une seconde fois. Gardez map.resize() pour le seul cas que l'observateur ne voit pas, ou si vous passez trackResize: false.

Les marqueurs HTML sont de simples éléments du DOM. Ils ne passent pas par les gabarits Angular et c'est tant mieux : cent composants dynamiques pour cent pastilles coûtent cher à chaque cycle. Un bouton créé à la main, avec un aria-label, suffit. Seul le clic revient dans la zone, parce qu'il change l'état de la page.

carte.component.ts, les marqueurs et la destruction

readonly lieux = input<{ id: string; nom: string; coord: [number, number] }[]>([]);
readonly lieuChoisi = output<string>();
private marqueurs: Marker[] = [];

private readonly poserMarqueurs = effect(() => {
  const map = this.carte();
  const lieux = this.lieux();
  const Marker = this.maplibre?.Marker;
  if (!map || !Marker) return;
  this.marqueurs.forEach((m) => m.remove());
  this.marqueurs = lieux.map((lieu) => {
    const el = document.createElement('button');
    el.type = 'button';
    el.className = 'marqueur';
    el.setAttribute('aria-label', lieu.nom);
    el.addEventListener('click', () => this.zone.run(() => this.lieuChoisi.emit(lieu.id)));
    return new Marker({ element: el }).setLngLat(lieu.coord).addTo(map);
  });
});

private readonly nettoyer = inject(DestroyRef).onDestroy(() => {
  this.detruit = true;
  this.marqueurs.forEach((m) => m.remove());
  this.carte()?.remove();
});

Au-delà de quelques centaines de points, quittez les marqueurs HTML pour une couche circle ou symbol dans une source GeoJSON : le rendu passe sur la carte graphique.

map.remove() n'est pas une politesse. La documentation de MapLibre l'écrit : elle libère les éléments du DOM, les écouteurs, les web workers et les ressources WebGL. Le code de MapLibre le rappelle aussi : la réserve de workers préchauffée ne se vide que lorsque toutes les cartes ont été retirées par map.remove(). Une application qui navigue entre dix fiches avec carte, sans rien rendre, garde tout en mémoire.

Rendu serveur : ce qui casse, et ce qui passe

Le 27 septembre 2026, nous avons importé maplibre-gl 6.11.2 sous Node 20.17, sans navigateur. L'import passe. La construction échoue : new Map() lève « document is not defined ». Le module se charge donc côté serveur sans dommage, c'est la carte qui ne peut pas y naître.

La règle tient en une ligne de la documentation d'Angular : les rappels de rendu, dont afterNextRender, ne s'exécutent ni pendant le rendu serveur ni pendant le pré-rendu. Une carte créée là est sûre par construction. Le serveur rend le conteneur vide, à la bonne hauteur, et le navigateur y pose la carte. Réservez une hauteur fixe au conteneur : sans elle, la page saute à l'arrivée de la carte et le score de stabilité visuelle en pâtit.

Pour le code qui doit décider ailleurs, un service qui précharge le style par exemple, isPlatformBrowser(inject(PLATFORM_ID)) reste la bonne garde.

un service qui ne touche au navigateur que sur le navigateur

import { Injectable, PLATFORM_ID, inject } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';

@Injectable({ providedIn: 'root' })
export class PrechargementCarte {
  private readonly navigateur = isPlatformBrowser(inject(PLATFORM_ID));

  precharger(): void {
    if (!this.navigateur) return;
    void import('maplibre-gl').then((m) => m.prewarm());
  }
}

Quand vous n'avez pas à écrire ce composant

Un composant MapLibre bien fait tient en une centaine de lignes. Il ne fournit ni fond de carte, ni itinéraires, ni lieux, ni recherche d'adresse : tout cela reste à servir, à héberger et à tenir à jour. Si votre besoin est de montrer des randonnées, des boucles vélo et des lieux sur une page, la carte La Trace se pose par le bloc à coller ou par le SDK, et le composant Angular se réduit à un conteneur. Elle sert aujourd'hui 134 531 itinéraires publiés, sur 2 248 cartes qui ont reçu au moins une visite depuis le 10 avril 2026.

La carte du Parc naturel régional de Chartreuse, telle qu'elle s'intègre dans une page : itinéraires, lieux et recherche d'adresse, sans composant à maintenir.