Where to Find GeoLibre Developer Documentation: A Complete Guide for Contributors and Extenders

GeoLibre developer documentation lives in the docs/ folder of the opengeos/GeoLibre repository, with the README.md serving as the primary entry point linking to all guides.

GeoLibre is a full-stack geospatial platform built as an npm workspaces monorepo. It ships a React UI, Tauri-based desktop client, mobile builds, and a Python/Jupyter embed. All developer-facing documentation is version-controlled alongside the source code, ensuring what you read always matches what you build.

Quick Navigation to GeoLibre Developer Docs

The repository organizes documentation into focused guides covering every aspect of development. Here are the essential files with direct GitHub links:

• Getting Started — Clone, install dependencies, and run web, desktop, or Docker builds: [docs/getting-started.md](https://github.com/opengeos/GeoLibre/blob/main/docs/getting-started.md)
• Architecture — Package structure, store flow, 3D globe integration, DuckDB-WASM vector import, Python sidecar, and offline PWA caching: [docs/architecture.md](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md)
• Contributing — Coding standards, CI gates, linting, pre-commit hooks, and PR workflow: [docs/contributing.md](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)
• Project Format — Specification of the .geolibre.json project file and store serialization: [docs/project-format.md](https://github.com/opengeos/GeoLibre/blob/main/docs/project-format.md)
• Plugin API — How to write, register, and publish built-in or external plugins: [docs/plugin-api.md](https://github.com/opengeos/GeoLibre/blob/main/docs/plugin-api.md)
• Python Package — Embedding the UI in Jupyter notebooks and driving the map via the geolibre API: [docs/python.md](https://github.com/opengeos/GeoLibre/blob/main/docs/python.md)
• R Package — Documentation for the geolibre R interactive widget: [docs/r.md](https://github.com/opengeos/GeoLibre/blob/main/docs/r.md)
• Self-Hosting & Docker — Docker deployment and FastAPI sidecar configuration: [docs/self-hosting.md](https://github.com/opengeos/GeoLibre/blob/main/docs/self-hosting.md)
• Roadmap & Features — Planned enhancements and current capabilities: [docs/roadmap.md](https://github.com/opengeos/GeoLibre/blob/main/docs/roadmap.md)

User guides live under docs/user-guide/ with tutorials on adding data, styling layers, processing tools, AI assistant integration, and embedding.

Key Source Files for GeoLibre Developers

Understanding the codebase requires familiarity with these core files:

File	Purpose
README.md	Entry point with badges, quick install, and documentation links
packages/core/src/store.ts	Global Zustand store that drives the entire UI
packages/map/src/MapController.ts	Syncs store state to MapLibre GL JS sources and layers
apps/geolibre-desktop/src/hooks/usePlugins.ts	Plugin registration entry point
backend/geolibre_server/README.md	Optional FastAPI sidecar for vector/raster conversion and AI proxy
docker/nginx.conf	Nginx config for official Docker images
scripts/gen-whitebox-menu-catalog.mjs	Generates Processing menu catalog after geolibre-wasm updates
packages/plugins/src/plugins/deckgl-viz/store-layer.ts	Example Deck.gl visualization plugin

Running GeoLibre from Source

The fastest way to start developing is cloning the repository and running the Vite dev server. These steps are documented in docs/getting-started.md:

# Clone and install

git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre
npm install   # or `bun install`

# Start the web UI

npm run dev    # → http://localhost:5173

Working with the Core Store

The Zustand-based store in packages/core/src/store.ts manages all application state. Here's how to programmatically add a vector layer:

import { useStore } from '@geolibre/core';
import { addGeoJsonLayer } from '@geolibre/core';

const geojson = {
  type: 'FeatureCollection',
  features: [{
    type: 'Feature',
    geometry: { type: 'Point', coordinates: [0, 0] },
    properties: {}
  }]
};

const store = useStore();
store.dispatch(addGeoJsonLayer({ name: 'My Point', data: geojson }));

The store implementation and layer sync flow are detailed in docs/architecture.md#state-flow.

Embedding GeoLibre in Python and Jupyter

The geolibre Python wheel enables embedded UIs in notebooks. Install and launch with:

# Install once

!pip install geolibre

# Launch embedded map

from geolibre import GeoLibre
map = GeoLibre()
map.add_vector('https://raw.githubusercontent.com/opengeos/GeoLibre/main/tests/geojson/sample.geojson')
map

Full API reference is in [docs/python.md](https://github.com/opengeos/GeoLibre/blob/main/docs/python.md).

Creating a Custom GeoLibre Plugin

Plugins extend functionality through a standardized registration pattern. Create a plugin in packages/plugins/src/plugins/:

// packages/plugins/src/plugins/example-plugin.ts
import { Plugin } from '@geolibre/plugins';

export const examplePlugin: Plugin = {
  id: 'example',
  name: 'Example Plugin',
  register: ({ store }) => {
    store.subscribe(state => console.log('store updated', state));
  }
};

Register the plugin in apps/geolibre-desktop/src/hooks/usePlugins.ts and rebuild. The complete plugin lifecycle is documented in [docs/plugin-api.md](https://github.com/opengeos/GeoLibre/blob/main/docs/plugin-api.md).

Self-Hosting with Docker

For production deployments, GeoLibre provides an official Docker image with configurable Nginx settings in docker/nginx.conf. The optional FastAPI sidecar handles vector/raster conversion and AI proxying—configuration details are in backend/geolibre_server/README.md and docs/self-hosting.md.

Summary

• Primary entry point: README.md at the repository root
• All docs location: docs/ folder with 10+ specialized guides
• Core architecture: Zustand store (packages/core/src/store.ts) drives MapLibre GL JS via MapController.ts
• Extension points: Plugin API for custom features, Python/R packages for embedding
• Deployment: Docker support with FastAPI sidecar for advanced workflows

Frequently Asked Questions

What is the fastest way to get started with GeoLibre development?

Clone the repository, run npm install, and execute npm run dev to launch the Vite development server at http://localhost:5173. Complete instructions are in docs/getting-started.md.

Where can I find the GeoLibre plugin API documentation?

The Plugin API guide at [docs/plugin-api.md](https://github.com/opengeos/GeoLibre/blob/main/docs/plugin-api.md) covers writing, registering, and publishing plugins. Reference implementation: packages/plugins/src/plugins/deckgl-viz/store-layer.ts.

How do I embed GeoLibre in a Jupyter notebook?

Install the geolibre Python wheel with pip install geolibre, import from geolibre import GeoLibre, and call the .add_vector() method to load data. See docs/python.md for the full embedding API.

Is GeoLibre documentation version-controlled with the code?

Yes. All GeoLibre developer documentation resides in the same repository under the docs/ folder, ensuring documentation always matches the code version you are building.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}