GeoLeaf — Utilisation via CDN et NPM

Version produit : GeoLeaf Platform V2 Version : 2.0.0 Dernière mise à jour : mars 2026

Convention de versioning : Platform V2 est le label produit ; le SemVer technique des packages/releases est en 2.0.x. Voir VERSIONING_POLICY.md.

Ce document décrit les méthodes recommandées pour charger GeoLeaf dans une application web :

via CDN UNPKG ;
via CDN jsDelivr ;
via NPM / ESM dans un bundler moderne ;
via un bundle ESM local (dist/geoleaf.esm.js) ;
avec un exemple HTML complet ;
avec des avertissements API autour de GeoLeaf.Core.init(...).

Note v2.0.0 : GeoLeaf distribue exclusivement en ESM. Il n'y a plus de bundle UMD (geoleaf.min.js). Utiliser <script type="module"> ou un bundler moderne (Vite, Webpack, Rollup).

Note : les URLs CDN ci-dessous supposent que le package @geoleaf/core est publié sur NPM.

Peer dependency : maplibre-gl ^5.0.0 doit être chargé séparément — il n'est pas inclus dans le bundle GeoLeaf.

Périmètre licence : le package @geoleaf/core est sous licence MIT. Les plugins premium (Storage, AddPOI) sont distribués séparément sous licence commerciale.

1. Utilisation via UNPKG (CDN)

html

<!-- MapLibre GL JS (peer dependency — doit être chargé avant GeoLeaf) -->
<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css" />

<!-- GeoLeaf styles -->
<link rel="stylesheet" href="https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf-main.min.css" />

<!-- GeoLeaf ESM (via script type="module") -->
<script type="module">
    import { Core } from "https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf.esm.js";
    // ...
</script>

2. Utilisation via jsDelivr (CDN)

html

<!-- MapLibre GL JS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5/dist/maplibre-gl.css" />

<!-- GeoLeaf styles -->
<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@geoleaf/core@2.0.0/dist/geoleaf-main.min.css"
/>

<!-- GeoLeaf ESM -->
<script type="module">
    import { Core } from "https://cdn.jsdelivr.net/npm/@geoleaf/core@2.0.0/dist/geoleaf.esm.js";
    // ...
</script>

3. Utilisation locale du bundle ESM (dist/)

html

<!-- MapLibre GL JS (depuis CDN ou bundle local) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5/dist/maplibre-gl.css" />

<!-- GeoLeaf styles locaux -->
<link rel="stylesheet" href="/dist/geoleaf-main.min.css" />

<!-- GeoLeaf ESM local -->
<script type="module">
    import { Core } from "/dist/geoleaf.esm.js";
    // ...
</script>

4. Import NPM / ESM dans un bundler moderne

bash

npm install @geoleaf/core maplibre-gl

typescript

import maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";

import { Core } from "@geoleaf/core";
import "@geoleaf/core/dist/geoleaf-main.min.css";

Core.init({
    mapId: "geoleaf-map",
    center: [-60.65, -32.95], // [longitude, latitude]
    zoom: 12,
    theme: "light",
});

5. Exemple HTML complet

html

<!DOCTYPE html>
<html lang="fr">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Exemple GeoLeaf — CDN ESM</title>

        <!-- MapLibre GL JS (peer dependency) -->
        <link
            rel="stylesheet"
            href="https://cdn.jsdelivr.net/npm/maplibre-gl@5/dist/maplibre-gl.css"
        />

        <!-- GeoLeaf styles -->
        <link
            rel="stylesheet"
            href="https://cdn.jsdelivr.net/npm/@geoleaf/core@2.0.0/dist/geoleaf-main.min.css"
        />

        <style>
            html,
            body {
                margin: 0;
                padding: 0;
                height: 100%;
            }
            #geoleaf-map {
                width: 100vw;
                height: 100vh;
            }
        </style>
    </head>
    <body>
        <div id="geoleaf-map"></div>

        <script type="module">
            import { Core } from "https://cdn.jsdelivr.net/npm/@geoleaf/core@2.0.0/dist/geoleaf.esm.js";

            document.addEventListener("DOMContentLoaded", () => {
                Core.init({
                    mapId: "geoleaf-map",
                    center: [-60.65, -32.95], // [longitude, latitude]
                    zoom: 12,
                    theme: "light",
                });
            });
        </script>
    </body>
</html>

6. API `GeoLeaf.Core.init(...)`

typescript

interface GeoLeafCoreInitOptions {
    mapId: string;
    center: [number, number]; // [longitude, latitude] — MapLibre GL JS convention
    zoom: number;
    theme?: string;
    basemapId?: string;
    configUrl?: string;
    onReady?: (ctx: GeoLeafCoreContext) => void;
    onError?: (error: unknown) => void;
}

interface GeoLeafCoreContext {
    map: maplibregl.Map;
    baselayers?: unknown;
    ui?: unknown;
    config?: unknown;
}

Note : Le type map dans le contexte est maplibregl.Map. Les coordonnées suivent la convention MapLibre GL JS : [longitude, latitude].

7. Artefacts dist/

Structure réelle du répertoire dist/ après build :

dist/
 ├─ geoleaf.esm.js          ← Bundle ESM principal (CDN, bundlers)
 ├─ geoleaf-main.min.css    ← Styles minifiés (PostCSS/cssnano)
 ├─ esm/
 │   └─ bundle-esm-entry.js ← ESM avec exports nommés (code splitting)
 ├─ chunks/
 │   ├─ poi-core.js         ← Chunk lazy POI core
 │   ├─ poi-renderers.js    ← Chunk lazy POI renderers
 │   ├─ route.js            ← Chunk lazy Route
 │   └─ ...                 ← Autres chunks lazy
 └─ types/
     └─ bundle-esm-entry.d.ts ← Types TypeScript

8. Avertissements API

Charger MapLibre GL JS avant GeoLeaf (peer dependency).
Utiliser <script type="module"> — pas de script classique sans type="module".
Ne pas mélanger ESM CDN et bundle local.
Coordonnées : GeoLeaf v2 suit la convention MapLibre GL JS [longitude, latitude].
Versionner explicitement les URLs CDN (ex : @2.0.0, pas @latest).
Prévoir un fallback local en production.

9. Check-list intégration

[ ] MapLibre GL JS CSS chargé
[ ] MapLibre GL JS JS chargé (peer dependency)
[ ] GeoLeaf CSS chargé
[ ] GeoLeaf ESM importé (type="module")
[ ] window.GeoLeaf défini
[ ] Core.init() disponible
[ ] Carte visible dans le DOM (hauteur CSS définie)
[ ] Coordonnées au format [longitude, latitude]
[ ] URLs CDN versionnées explicitement

10. Extensions commerciales

Des extensions commerciales optionnelles sont disponibles pour GeoLeaf :

@geoleaf-plugins/storage — Cache hors-ligne IndexedDB
@geoleaf-plugins/addpoi — Formulaires CRUD POI

Distribués via GitHub Packages (npm.pkg.github.com). Pour plus d'informations : geoleaf.dev.

GeoLeaf — Utilisation via CDN et NPM ​

1. Utilisation via UNPKG (CDN) ​

2. Utilisation via jsDelivr (CDN) ​

3. Utilisation locale du bundle ESM (dist/) ​

4. Import NPM / ESM dans un bundler moderne ​

5. Exemple HTML complet ​

6. API GeoLeaf.Core.init(...) ​

7. Artefacts dist/ ​

8. Avertissements API ​

9. Check-list intégration ​

10. Extensions commerciales ​

GeoLeaf — Utilisation via CDN et NPM

1. Utilisation via UNPKG (CDN)

2. Utilisation via jsDelivr (CDN)

3. Utilisation locale du bundle ESM (dist/)

4. Import NPM / ESM dans un bundler moderne

5. Exemple HTML complet

6. API `GeoLeaf.Core.init(...)`

7. Artefacts dist/

8. Avertissements API

9. Check-list intégration

10. Extensions commerciales