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

> Set up the GeoLibre development environment from source. Follow our guide to install Node.js Rust Python and run npm install and npm run dev or tauri dev for quick local development.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)** at the [Prerequisites section](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md#prerequisites).

## Clone the GeoLibre Repository

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

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

```

See the [Setup section](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md#setup) in the contributing guide for additional context.

## Install Node.js and Python Dependencies

Install all JavaScript/TypeScript packages across the monorepo:

```bash
npm install

```

The repository tracks a **[`package-lock.json`](https://github.com/opengeos/GeoLibre/blob/main/package-lock.json)** at the root. Using `npm` (not `pnpm` or `yarn`) guarantees reproducible installs across environments.

For Python documentation builds or sidecar development:

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

```

## Run the Web Development Server

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

```bash
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:

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src-tauri/Cargo.toml)**, while Python sidecar dependencies live in **[`backend/geolibre_server/pyproject.toml`](https://github.com/opengeos/GeoLibre/blob/main/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.

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/pyproject.toml) modification.

## Verify Code Quality Before Committing

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

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

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

```

For quick frontend validation:

```bash
npm run test:frontend

```

## GeoLibre Architecture Overview

Understanding the modular structure helps navigate the codebase effectively:

- **`@geolibre/core`** (**[`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts)**) — Zustand store, domain types, and [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) project schema
- **`@geolibre/map`** (**[`packages/map/src/map-controller.ts`](https://github.com/opengeos/GeoLibre/blob/main/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**](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md) ([`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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

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

```

### Desktop Development Quickstart

```bash
npm run tauri:dev

```

### Python Sidecar Quickstart

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

```

### Pre-Commit Verification

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/package.json)**, **[`Cargo.toml`](https://github.com/opengeos/GeoLibre/blob/main/Cargo.toml)** for Tauri, and **[`pyproject.toml`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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.