How to Access the GeoLibre Repository Structure: A Complete Monorepo Guide

The GeoLibre repository is an npm workspaces monorepo that organizes React front-ends, TypeScript libraries, Python tooling, and a FastAPI sidecar into top-level directories such as apps/, packages/, workers/, backend/, and python/ under a single root package.json.

GeoLibre is an open-source geospatial platform maintained at opengeos/GeoLibre as a unified monorepo. To access the GeoLibre repository structure effectively, you need to understand how the top-level directories are wired together under one shared package-lock.json. Every sub-package is authored in TypeScript (*.ts / *.tsx) except the Python sidecar (*.py), and tests live under the top-level tests/ folder.

GeoLibre Repository Structure Overview

GeoLibre is organized as a single npm workspaces monorepo that groups together all front-end, back-end, and auxiliary components. The root package.json declares the workspace layout with:

"workspaces": ["apps/*", "packages/*", "workers/*"]

Because the repository is a monorepo, every sub-package has its own package.json, but they all share the same lockfile (package-lock.json) at the root. Installing once with npm install wires up every workspace automatically.

The apps/ Directory

The apps/ directory contains the three ways the React UI is built:

• apps/geolibre-desktop – Desktop build using Tauri v2.
• Web – Vite-served browser build.
• apps/geolibre-desktop/dist-embed – Embedded build that bundles the web app into the Python anywidget.

The packages/ Directory

The packages/ directory holds reusable libraries that the apps share:

• @geolibre/core (packages/core) – Zustand store, domain types, and project schema.
• @geolibre/map (packages/map) – MapLibre-GL lifecycle and layer synchronization.
• @geolibre/ui (packages/ui) – UI primitives built with shadcn-style components.
• @geolibre/processing (packages/processing) – Client-side algorithm registry.
• @geolibre/plugins (packages/plugins) – Built-in plugin interface and implementations.

Supporting Infrastructure: workers/, backend/, and python/

Beyond the front-end and shared libraries, the GeoLibre repository structure includes several specialized directories:

• workers/ – TypeScript workers that run heavy processing in a separate thread. The main worker lives under workers/viewer.
• backend/ – A FastAPI sidecar that provides optional vector, raster, and conversion services. It is located in backend/geolibre_server and is started on demand by the desktop app.
• python/ – The Python package that ships the anywidget embedding. It also contains a small CLI, geolibre-mcp, for authoring .geolibre.json projects.

Command-Line Navigation for the GeoLibre Monorepo

To quickly orient yourself after you clone the repo, use the following commands.

List every workspace:

npm run workspaces:list

Or use:

npm ls --workspaces

To focus on a particular part of the code, change into its folder:

cd packages/core
cd apps/geolibre-desktop
cd backend/geolibre_server

All tests live under the top-level tests/ folder and follow the same workspace naming conventions.

Development Commands and Entry Points

Start the Web Development Server

Runs the browser build and watches all workspaces:

npm run dev

# → Vite dev server listening on http://localhost:5173

Run the Desktop App Locally

Requires Tauri v2:

npm run tauri:dev

# Opens the native desktop window with full filesystem access

Build the Production Web Bundle

Produces apps/geolibre-desktop/dist/:

npm run build

Launch the FastAPI Sidecar

For Python-only tools, move into the backend directory:

cd backend/geolibre_server
uv run --frozen --project . uv run backend/geolibre_server/main.py

Inspect the Core Store

Open the Zustand store definition directly:

code packages/core/src/store.ts

Add a New Plugin

Create a skeleton and register it:

mkdir -p packages/plugins/src/plugins/my-plugin
echo "export * from './my-plugin';" >> packages/plugins/src/index.ts

Run the Full Test Suite

Includes front-end, back-end, and end-to-end tests:

npm run ci

Key Source Files and Entry Points

When you access the GeoLibre repository structure, bookmark these authoritative files:

• package.json (root) – Declares the workspace layout and top-level scripts.
• apps/geolibre-desktop/src/hooks/usePlugins.ts – Registers built-in plugins; central for extending functionality.
• packages/core/src/store.ts – Defines the Zustand store that serves as the single source of truth for the app.
• packages/map/src/MapCanvas.tsx – Synchronizes MapLibre sources and layers with the store.
• backend/geolibre_server/app/main.py – Entry point for the FastAPI sidecar.
• python/src/geolibre/__init__.py – Exposes the Python anywidget version of GeoLibre.
• tests/vector-layer-sync.test.ts – Drives much of the UI code and demonstrates front-end testing patterns.
• CLAUDE.md – Contains repository-specific guidance for developers.

Summary

• The GeoLibre codebase is a unified npm workspaces monorepo with one root package.json and a shared package-lock.json.
• The apps/ directory houses the desktop, web, and embedded React builds, while packages/ contains shared libraries such as @geolibre/core, @geolibre/map, and @geolibre/plugins.
• Heavy processing threads live in workers/, optional Python services live in backend/, and the anywidget/Python CLI tooling lives in python/.
• You can list workspaces with npm ls --workspaces, start the web server with npm run dev, and open the desktop app with npm run tauri:dev.
• Critical entry points include packages/core/src/store.ts, packages/map/src/MapCanvas.tsx, and backend/geolibre_server/app/main.py.

Frequently Asked Questions

Where is the GeoLibre desktop application source code located?

The desktop application source code lives inside apps/geolibre-desktop. This directory contains a Tauri v2 wrapper that provides native filesystem access, and it also outputs the embedded build to apps/geolibre-desktop/dist-embed for the Python anywidget.

How do I list all workspaces in the GeoLibre monorepo?

Run npm ls --workspaces from the repository root. Because GeoLibre uses npm workspaces, the root package.json defines "workspaces": ["apps/*", "packages/*", "workers/*"], so every sub-package is automatically discovered under a single lockfile.

What is the purpose of the packages/core/src/store.ts file?

packages/core/src/store.ts implements the Zustand store that acts as the single source of truth for application state. It is imported by both the UI and map packages to keep domain types, project schema, and runtime data synchronized across the monorepo.

How do I start the Python FastAPI backend when working with GeoLibre?

Navigate to backend/geolibre_server and run the FastAPI entry point with uv run --frozen --project . uv run backend/geolibre_server/main.py. The desktop app can start this sidecar on demand when it needs optional vector, raster, or conversion services.

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