Architecture performance — GeoLeaf

Product Version : GeoLeaf Platform V2

Version : 2.0.0

Dernière mise à jour : mars 2026

---

Court document sur les choix techniques liés à la performance dans GeoLeaf (Worker GeoJSON, lazy loading, requestIdleCallback, rendu MapLibre GL JS, bonnes pratiques).

---

1. Worker GeoJSON

Le chargement des couches GeoJSON peut faire du fetch + parse dans un Web Worker pour ne pas bloquer le thread principal. Si le Worker est indisponible ou si les données viennent du cache, le parse peut s'effectuer sur le main thread (gros fichiers = risque de freeze).

• Fichiers concernés : packages/core/src/modules/built-in/geojson/ (loader, worker).
• Bonnes pratiques : pour les très gros GeoJSON, privilégier la découpe en plusieurs couches, le lazy loading par vue, ou les vector tiles si le profil le permet.

---

2. Lazy loading (code splitting)

• Modules secondaires : POI, Route, Legend, LayerManager, Labels, Themes, Table, Search sont chargés en chunks ESM (import dynamique). Le bundle ESM CDN (geoleaf.esm.js) inclut inlineDynamicImports: true ; le mode npm/bundler produit des chunks séparés dans dist/chunks/.
• Préchargement : _loadAllSecondaryModules() est déclenché tôt pour chevaucher le téléchargement des chunks avec l'init UI/Storage, puis await avant d'utiliser les modules.
• Lazy UI : lazyLoadImage (IntersectionObserver), lazyExecute (report d'exécution via requestIdleCallback ou setTimeout) dans les helpers DOM.

---

3. requestIdleCallback

Utilisé pour répartir le travail et garder l'UI réactive :

• GeoJSON : après parse (Worker ou main), l'ajout des features à la couche MapLibre GL est fait par chunks (ex. 200 features par batch) via requestIdleCallback (fallback setTimeout) pour ne pas bloquer le main thread. Voir geojson/loader/single-layer.ts (_addFeaturesChunked).
• Profil / couches : planification de tâches lourdes (ex. chargement de couches) avec requestIdleCallback (timeout 3000 ms) ou setTimeout en fallback. Voir geojson/loader/profile.ts.
• Helpers : lazyExecute(callback, timeout) utilise requestIdleCallback si disponible.

---

4. Rendu MapLibre GL JS

GeoLeaf utilise MapLibre GL JS ^5.0.0 comme moteur cartographique. Caractéristiques clés :

• Rendu WebGL : toutes les couches vectorielles et raster sont rendues sur le GPU via WebGL.
• Style expression : les filtres, couleurs et visibilité sont exprimés comme des expressions MapLibre GL Style Spec — évalués par le moteur de rendu, pas en JavaScript.
• Source GeoJSON : les données GeoJSON sont injectées via map.getSource(id).setData(geojson) pour les mises à jour incrémentales sans recréer la couche.
• Clustering natif : le clustering POI utilise le clustering intégré MapLibre GL (côté source, pas de recalcul JS).

---

5. Bonnes pratiques

Sujet	Recommandation
Taille GeoJSON	Éviter un seul fichier énorme ; découper en couches ou par zone/vue si possible. En cas de gros fichier, le Worker + chunked addData limitent le freeze.
Nombre de couches	Limiter le nombre de couches actives simultanées si les données sont lourdes ; utiliser la visibilité par thème et le lazy loading des couches.
Bundle lite	Objectif < 130 KB gzip pour geoleaf-lite.esm.js ; vérifier avec npm run benchmark et dist/stats.html.
Métriques runtime	Utiliser GeoLeaf.getPerformanceMetrics() ou GeoLeaf.boot({ onPerformanceMetrics }) pour suivre le temps jusqu'à première couche et interactivité.
Expressions de style	Préférer les expressions MapLibre GL Style Spec aux fonctions JS pour le filtrage et le style (exécutées sur le thread de rendu).
resize()	Appeler map.resize() après tout changement de dimensions du conteneur (fullscreen, panneau latéral). Utiliser CONSTANTS.FULLSCREEN_TRANSITION_MS comme délai.

---

6. Budget bundle

Artefact	Cible	Commande de vérification
geoleaf.esm.js (gzip)	~35 KB	npm run benchmark
geoleaf-lite.esm.js (gzip)	< 130 KB	dist/stats.html
Chunk search (FlexSearch)	~6 KB gzip	lazy-loadé uniquement si activé

---

Voir aussi

• packages/core/docs/performance/CSS_ANIMATION_OPTIMIZATION.md — optimisation des animations CSS
• packages/core/docs/ARCHITECTURE_GUIDE.md — architecture modulaire et séquence boot
• packages/core/docs/geojson/GEOJSON_LAYERS_GUIDE.md — couches GeoJSON
• packages/core/docs/PERFORMANCE_METRICS.md — métriques runtime et cibles bundle lite