How to Set Up the GeoLibre Development Environment from Source: A Complete Guide

Set up the GeoLibre development environment by installing Node.js 22+, Rust, and Python 3.10+, then run npm install and npm run dev for web development or npm run tauri:dev for desktop builds.

GeoLibre is an open-source geospatial mapping application built with React, MapLibre GL JS, and Tauri v2. This guide walks through the complete GeoLibre development environment setup from source, covering monorepo configuration, dependency installation, and running both web and desktop development servers.

Prerequisites for GeoLibre Development

Before cloning the repository, ensure your system meets these requirements:

Tool	Minimum Version	Purpose
Node.js	22+	Powers the npm workspaces monorepo and builds the React/Tauri UI
Rust	latest (via rustup)	Required for the Tauri desktop shell and native Rust plugins
Python	3.10+	Supports the optional FastAPI sidecar (backend/geolibre_server) and pre-commit hooks
Linux dependencies	webkit2gtk and libayatana-appindicator	Required by Tauri on Linux distributions

The complete prerequisite list is documented in docs/contributing.md at the Prerequisites section.

Clone the GeoLibre Repository

GeoLibre uses a single npm workspaces monorepo. One npm install at the root wires up every package automatically.

git clone https://github.com/YOUR_GITHUB_USERNAME/GeoLibre.git
cd GeoLibre

See the Setup section in the contributing guide for additional context.

Install Node.js and Python Dependencies

Install all JavaScript/TypeScript packages across the monorepo:

npm install

The repository tracks a package-lock.json at the root. Using npm (not pnpm or yarn) guarantees reproducible installs across environments.

For Python documentation builds or sidecar development:

python -m pip install -r requirements-docs.txt

Run the Web Development Server

Start the Vite-powered React UI with live-reload:

npm run dev

Open http://localhost:5173 in your browser. This builds the MapLibre map interface with automatic refresh on file changes.

Run the Desktop Development Server (Tauri v2)

Launch the Tauri v2 shell for native desktop capabilities:

npm run tauri:dev

The Tauri dev mode requires the Rust toolchain. This provides native file dialogs, local MBTiles access, and other desktop-only features unavailable in the web build.

Rust dependencies are declared in apps/geolibre-desktop/src-tauri/Cargo.toml, while Python sidecar dependencies live in backend/geolibre_server/pyproject.toml.

Optional: Start the Python Sidecar

The FastAPI sidecar powers the Whitebox toolbox and conversion utilities. It is only needed for server-side processing pipeline development.

cd backend/geolibre_server
uv sync                    # or `pip install -e .[test]`

uv run geolibre_server     # starts FastAPI on http://127.0.0.1:8765

The sidecar's lockfile at backend/geolibre_server/uv.lock is enforced in CI. Run uv lock --project backend/geolibre_server after any pyproject.toml modification.

Verify Code Quality Before Committing

Run the local quality gate to catch issues before submitting pull requests:

pre-commit run --all-files      # formatting, linting, type checking

npm run ci                      # full build, unit tests, worker checks, Rust validation

For quick frontend validation:

npm run test:frontend

GeoLibre Architecture Overview

Understanding the modular structure helps navigate the codebase effectively:

• @geolibre/core (packages/core/src/store.ts) — Zustand store, domain types, and .geolibre.json project schema
• @geolibre/map (packages/map/src/map-controller.ts) — MapLibre GL JS lifecycle, layer synchronization, raster/vector source handling
• @geolibre/ui — Shared shadcn-style UI primitives and Tailwind utilities
• @geolibre/processing — Client-side Whitebox WASM algorithm registry
• @geolibre/plugins — Plugin API and built-in extensions
• geolibre-desktop — Tauri shell with I/O bridging and package composition
• backend/geolibre_server — Optional FastAPI sidecar for heavy processing tasks

The Architecture document (docs/architecture.md) contains detailed package responsibilities and visual flow diagrams.

Common Setup Issues and Fixes

Symptom	Root Cause	Solution
npm run tauri:dev fails with "cannot find cargo"	Missing Rust toolchain	Install via rustup and ensure cargo is on $PATH
Backend tests fail with "Permission denied" on lockfile	uv.lock in non-writable directory	Run uv lock --project backend/geolibre_server after pyproject.toml changes
Map tiles fail loading in Linux desktop build	Missing webkit2gtk library	Install libwebkit2gtk-4.0-dev via system package manager
Playwright e2e tests fail on first run	Browser binary missing	Run npx playwright install chromium once

Complete Setup Commands

Web Development Quickstart

git clone https://github.com/YOUR_GITHUB_USERNAME/GeoLibre.git
cd GeoLibre
npm install
npm run dev   # → http://localhost:5173

Desktop Development Quickstart

npm run tauri:dev

Python Sidecar Quickstart

cd backend/geolibre_server
uv sync
uv run geolibre_server   # → http://127.0.0.1:8765

Pre-Commit Verification

pre-commit run --all-files
npm run ci

Summary

• Install prerequisites: Node.js 22+, Rust, Python 3.10+, and Linux system libraries if applicable
• Use npm exclusively: The monorepo relies on package-lock.json for reproducible installs
• Choose your dev mode: npm run dev for web, npm run tauri:dev for desktop
• Optional sidecar: Run the FastAPI server from backend/geolibre_server for processing tools
• Quality gate: Always run pre-commit and npm run ci before submitting changes
• Key files: Root package.json, Cargo.toml for Tauri, and pyproject.toml for the Python sidecar

Frequently Asked Questions

What is the minimum Node.js version for GeoLibre development?

Node.js 22 or higher is required to power the npm workspaces monorepo and build the React/Tauri UI. Earlier versions may fail during package installation or build steps.

Can I use pnpm or yarn instead of npm?

No. GeoLibre tracks a package-lock.json at the repository root, and CI enforces npm compatibility. Using pnpm or yarn may produce lockfile conflicts and is not supported for the GeoLibre development environment setup from source.

Is the Python sidecar required for basic development?

No. The FastAPI sidecar in backend/geolibre_server is optional. It is only needed if you are developing or testing the Whitebox toolbox, conversion utilities, or server-side processing pipelines. Web and desktop map editing work without it.

Why does Tauri fail to start on Linux?

Linux distributions require additional system libraries: webkit2gtk-4.0-dev (or equivalent) and libayatana-appindicator3-dev. These provide the web rendering engine and system tray integration that Tauri v2 depends on.

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