GeoLeaf-JS — Getting Started

Package: @geoleaf/coreVersion: 2.0.0 License: MIT

Installation (npm/bundler — ESM)
Installation (CDN/ESM — browser)
Deux modes d'initialisation
First map (Core.init)
Projet complet avec profil (GeoLeaf.init)
Loading secondary modules (lazy)
TypeScript usage
Build & serve en local
Next steps

Installation (npm/bundler — ESM)

bash

npm install @geoleaf/core maplibre-gl

Peer dependency :
bash
npm install maplibre-gl
MapLibre GL JS est la seule dépendance externe requise. Le clustering (supercluster) et les sources vectorielles sont intégrés nativement dans MapLibre.

Import

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

Or import everything at once (triggers full boot):

import GeoLeaf from "@geoleaf/core";

Installation (CDN/ESM — browser)

Incluez MapLibre GL JS avant GeoLeaf. Utilisez <script type="module"> :

html

<!-- MapLibre GL JS (required peer dependency) -->
<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.0.0/dist/maplibre-gl.css" />
<script src="https://unpkg.com/maplibre-gl@5.0.0/dist/maplibre-gl.js"></script>

<!-- GeoLeaf Core (ESM) -->
<link rel="stylesheet" href="https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf-main.min.css" />
<script type="module" src="https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf.esm.js"></script>

<!-- Alternative CDN (jsDelivr) -->
<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@geoleaf/core@2.0.0/dist/geoleaf-main.min.css"
/>
<script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@geoleaf/core@2.0.0/dist/geoleaf.esm.js"
></script>

Apres chargement, window.GeoLeaf est disponible globalement.

Note : Verifiez la disponibilite du CDN avant utilisation en production. Le nom du package sur npm (et CDN) est @geoleaf/core — pas geoleaf. Le build UMD (geoleaf.min.js) n'est plus distribue depuis la v2.0.0.

Deux modes d'initialisation

GeoLeaf propose deux modes d'initialisation selon le niveau de complexité de votre projet :

Mode	API	Quand l'utiliser
Carte simple	`Core.init({ mapId, center, zoom })`	Prototype rapide, carte sans couches configurées via profil
Projet complet	`GeoLeaf.init({ map, data }) + GeoLeaf.boot()`	Application avec profil JSON (couches, filtres, thème, clustering…)

mermaid

flowchart TD
    A(["Démarrer"]) --> B{"Couches GeoJSON,\nfiltres, thème,\nclustering ?"}
    B -->|Oui| C["GeoLeaf.init() + GeoLeaf.boot()\n→ Projet complet avec profil"]
    B -->|Non| D{"Prototype rapide\nou démonstration ?"}
    D -->|Oui| E["Core.init()\n→ Carte simple, sans profil"]
    D -->|Non| C
    style C fill:#2d6a4f,color:#fff
    style E fill:#457b9d,color:#fff

Pour un projet réel, préférez GeoLeaf.init() avec un profil — c'est l'approche recommandée. Pour un tutoriel complet de zéro, voir QUICKSTART_TUTORIAL.md.

First map

CDN/ESM (browser)

html

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>GeoLeaf — First Map</title>
        <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.0.0/dist/maplibre-gl.css" />
        <link
            rel="stylesheet"
            href="https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf-main.min.css"
        />
        <style>
            #map {
                height: 500px;
                width: 100%;
            }
        </style>
    </head>
    <body>
        <div id="map"></div>

        <script src="https://unpkg.com/maplibre-gl@5.0.0/dist/maplibre-gl.js"></script>
        <script
            type="module"
            src="https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf.esm.js"
        ></script>
        <script type="module">
            GeoLeaf.Core.init({
                mapId: "map",
                center: [48.8566, 2.3522],
                zoom: 12,
            });
        </script>
    </body>
</html>

ESM (npm/bundler)

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

Core.init({
    mapId: "map",
    center: [48.8566, 2.3522],
    zoom: 12,
});

Projet complet avec profil (GeoLeaf.init)

Pour les projets avec couches GeoJSON configurées, filtres, thème et clustering, utilisez l'API haut niveau GeoLeaf.init() + GeoLeaf.boot() :

html

<script type="module">
    GeoLeaf.init({
        map: { target: "map" },
        data: {
            activeProfile: "mon-profil",
            profilesBasePath: "./profiles/",
        },
    });
    GeoLeaf.boot();
</script>

// ESM (npm)
import GeoLeaf from "@geoleaf/core";

GeoLeaf.init({
    map: { target: "map" },
    data: {
        activeProfile: "mon-profil",
        profilesBasePath: "./profiles/",
    },
});
GeoLeaf.boot();

GeoLeaf.init() charge le profil depuis ./profiles/mon-profil/profile.json et tous les fichiers de configuration associés (layers.json, taxonomy.json, ui.json, basemaps.json). GeoLeaf.boot() démarre le rendu de la carte.

Pour la structure complète d'un profil et un tutoriel pas-à-pas, voir QUICKSTART_TUTORIAL.md et PROFILES_GUIDE.md.

Loading secondary modules (lazy)

Secondary modules (POI, Route, Table, etc.) are lazy-loaded on demand to minimize initial bundle size.

// Load POI system (core + renderers + extras in correct order)
await GeoLeaf._loadModule("poi");

// Load a single module
await GeoLeaf._loadModule("route");
await GeoLeaf._loadModule("table");
await GeoLeaf._loadModule("legend");

// Load all secondary modules at once
await GeoLeaf._loadAllSecondaryModules();

// After loading, the modules are available on GeoLeaf.*
GeoLeaf.POI.init(config);
GeoLeaf.Route.init(config);

See ARCHITECTURE_GUIDE.md for the full list of lazy modules.

TypeScript usage

GeoLeaf-JS is written in TypeScript and ships type declarations.

import { Core, POI, UI, Filters, Helpers } from "@geoleaf/core";

Core.init({
    mapId: "map",
    center: [48.8566, 2.3522],
    zoom: 12,
});

Type declarations are available at dist/types/bundle-esm-entry.d.ts (automatically resolved via exports in package.json).

Build & serve en local

Pour construire et visualiser la démo localement :

bash

# Construire la variante core-only dans deploy/ (port 8766)
npm run build:deploy

# Construire avec le plugin Storage (port 8767)
npm run build:deploy:storage

# Construire avec tous les plugins (port 8768)
npm run build:deploy:all

La démo est servie automatiquement par les tests E2E Playwright (ports 8766–8768). Pour une visualisation manuelle, ouvrez deploy/index.html via un serveur statique local (ex. extension Live Server de VS Code, ou python -m http.server).

Consultez ARCHITECTURE_GUIDE.md pour l'architecture détaillée du système de build et des variantes de déploiement.

Next steps

Objectif	Document
Projet complet de zéro	QUICKSTART_TUTORIAL.md
Configuration d'un profil	PROFILES_GUIDE.md
Référence JSON complète	PROFILE_JSON_REFERENCE.md
Développer un plugin custom	PLUGIN_DEVELOPMENT_GUIDE.md
Configurer les plugins (Storage, AddPOI)	PLUGIN_CONFIGURATION_GUIDE.md
Authentification API backend	CONNECTOR_GUIDE.md
API reference complète	API_REFERENCE.md
Architecture & boot	ARCHITECTURE_GUIDE.md
Intégration CDN détaillée	usage-cdn.md
Recettes courantes	COOKBOOK.md
Support PWA	pwa/pwa.md

GeoLeaf-JS — Getting Started ​

Table of contents ​

Installation (npm/bundler — ESM) ​

Import ​

Installation (CDN/ESM — browser) ​

Deux modes d'initialisation ​

First map ​

CDN/ESM (browser) ​

ESM (npm/bundler) ​

Projet complet avec profil (GeoLeaf.init) ​

Loading secondary modules (lazy) ​

TypeScript usage ​

Build & serve en local ​

Next steps ​

GeoLeaf-JS — Getting Started

Table of contents

Installation (npm/bundler — ESM)

Import

Installation (CDN/ESM — browser)

Deux modes d'initialisation

First map

CDN/ESM (browser)

ESM (npm/bundler)

Projet complet avec profil (GeoLeaf.init)

Loading secondary modules (lazy)

TypeScript usage

Build & serve en local

Next steps