GeoLeaf-JS — FAQ

Package: @geoleaf/coreVersion: 2.0.0 License: MIT

---

Installation

What is the correct package name?

@geoleaf/core — available on the public npm registry.

npm install @geoleaf/core maplibre-gl

Le nom geoleaf (sans scope) est incorrect et fait reference a un package different sans rapport.

What is the CDN URL?

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

<!-- JS (ESM) -->
<script type="module" src="https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf.esm.js"></script>

<!-- jsDelivr alternative -->
<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>

What are the required peer dependencies?

npm install maplibre-gl

MapLibre GL JS (^5.0.0) est la seule dependance externe requise. Le clustering est integre nativement via supercluster (source clustering MapLibre) et les tuiles vectorielles sont gerees par les sources vectorielles natives de MapLibre.

---

Getting started

How do I create a basic map?

CDN/ESM:

<div id="map" style="height:500px"></div>
<script type="module">
    import { Core } from "https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf.esm.js";
    Core.init({
        mapId: "map",
        center: [2.3522, 48.8566], // [longitude, latitude] — convention MapLibre GL JS
        zoom: 12,
    });
</script>

ESM/npm:

import { Core } from "@geoleaf/core";
Core.init({ mapId: "map", center: [2.3522, 48.8566], zoom: 12 });

How do I load a JSON profile?

GeoLeaf.Core.init({
    mapId: "map",
    configUrl: "/profiles/my-profile.json",
});

Or using the loadConfig method:

await GeoLeaf.loadConfig("/profiles/my-profile.json");
// or with an inline object:
await GeoLeaf.loadConfig({ map: { center: [2.3522, 48.8566], zoom: 12 } });

---

GeoJSON & layers

How do I add GeoJSON layers?

GeoJSON layers are defined in the JSON profile and managed by GeoLeaf.LayerManager. There is no GeoLeaf.GeoJSON public API.

Add layers in your profile:

{
    "layers": [
        {
            "id": "regions",
            "type": "geojson",
            "url": "/data/regions.geojson",
            "style": { "color": "#e74c3c", "weight": 2 }
        }
    ]
}

Then access the layer manager:

await GeoLeaf._loadModule("layerManager");
GeoLeaf.LayerManager.init({ map });
GeoLeaf.LayerManager.refresh();

Layer visibility is managed through the LayerManager UI control (toggle buttons in the panel).

---

POI

How do I show POI markers?

The POI module is lazy-loaded. Load it before use:

await GeoLeaf._loadModule("poi");
GeoLeaf.POI.init(config);

POI configuration is defined in the JSON profile under the poi key.

---

Themes

How do I apply a UI theme (light/dark)?

GeoLeaf.setTheme("dark"); // via top-level API
GeoLeaf.Core.setTheme("dark"); // via Core facade

How do I apply a layer theme (style preset)?

await GeoLeaf.Themes.applyTheme("rivers", "dark");
const current = GeoLeaf.Themes.getCurrentTheme("rivers");
const available = await GeoLeaf.Themes.getAvailableThemes("rivers");

---

Secondary modules (lazy loading)

How do I load secondary modules?

// Single module
await GeoLeaf._loadModule("poi"); // POI system
await GeoLeaf._loadModule("route"); // Route/directions
await GeoLeaf._loadModule("table"); // Data table
await GeoLeaf._loadModule("legend"); // Legend panel

// All at once
await GeoLeaf._loadAllSecondaryModules();

Why is my module undefined after boot?

Secondary modules (POI, Route, Table, etc.) require explicit loading. The core bundle loads B1–B11 automatically, but secondary lazily-bundled modules need _loadModule() to be called first.

---

Plugins

How do I install the Storage plugin?

The Storage plugin (@geoleaf-plugins/storage) is a commercial product distributed via GitHub Packages. Requires authentication:

# Configure .npmrc
echo "@geoleaf-plugins:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_TOKEN" >> .npmrc

npm install @geoleaf-plugins/storage

Contact geoleaf.dev for licensing.

How do I check which plugins are loaded?

GeoLeaf.plugins.isLoaded("storage"); // → true/false
GeoLeaf.plugins.getLoadedPlugins(); // → ["core", "storage"]

ESM import : import { PluginRegistry } from "@geoleaf/core" pour les bundlers.

---

Troubleshooting

"GeoLeaf is not defined"

Verifiez que le script GeoLeaf utilise type="module" et que les CSS MapLibre sont charges :

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css" />
<link rel="stylesheet" href="https://unpkg.com/@geoleaf/core@2.0.0/dist/geoleaf-main.min.css" />
<script type="module" src="geoleaf.esm.js"></script>

GeoLeaf v2 est ESM-only. Le type="module" est obligatoire.

"APIController missing"

This means a facade method was called before the boot sequence completed. Wrap in an init callback or use await GeoLeaf.init(options).

"Module inconnu" warning in console

You passed an unknown name to GeoLeaf._loadModule(). Check the valid module names in ARCHITECTURE_GUIDE.md.

Map container not found

Ensure the DOM element exists before calling Core.init():

document.addEventListener("DOMContentLoaded", () => {
  GeoLeaf.Core.init({ mapId: "map", ... });
});

---

API conventions

GeoLeaf.GeoJSON — is there a public API?

GeoLeaf.GeoJSON is internal. Layer loading is configured in the JSON profile and accessed via GeoLeaf.LayerManager.

If you need layers loaded at runtime, define them in your profile or use the configuration API — see PROFILES_GUIDE.md.

GeoLeaf.BaseLayers vs GeoLeaf.Baselayers

Both work — BaseLayers is a backward-compatible alias for Baselayers. Prefer Baselayers (lowercase 'l') in new code.