GeoLibre Repository File System Commands: A Complete Guide to Project Structure and CLI Operations

The GeoLibre repository uses standard npm workspace commands (npm install, npm run build), package-specific scripts for development and testing, and Tauri CLI commands for cross-platform desktop builds.

The GeoLibre GIS platform is organized as a single-workspace npm monorepo that delivers cloud-native geospatial capabilities across browsers, desktop applications, mobile devices, and Jupyter notebooks. Understanding the repository's file system commands is essential for developers contributing to or extending the platform. This guide covers every key command for building, developing, testing, and packaging the codebase as implemented in the opengeos/GeoLibre repository.

Core Workspace Commands

All operations begin from the repository root where package.json defines the npm workspace structure.

Installing Dependencies

# Install all dependencies across workspaces

npm install

# Clean install (recommended for CI)

npm ci

The root package.json declares workspaces under apps/*, packages/*, backend/*, and extensions/*, allowing npm to hoist shared dependencies and link local packages automatically.

Running Development Servers

# Start the web development server

npm run dev

# Start with specific workspace

npm run dev --workspace=apps/geolibre-desktop

As configured in [package.json](https://github.com/opengeos/GeoLibre/blob/main/package.json), the dev script launches Vite-based development servers with hot module replacement.

Build Commands

GeoLibre supports multiple build targets through distinct npm scripts.

Web and Desktop Builds

# Production build for all targets

npm run build

# Build specific application

npm run build --workspace=apps/geolibre-desktop

The build process in [apps/geolibre-desktop/vite.config.ts](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/vite.config.ts) handles:

• Web assets — Bundled for browser deployment
• Desktop assets — Compiled for Tauri integration with platform-specific native code

Processing Catalog Generation

# Regenerate Whitebox tools menu (run after updating geolibre-wasm)

node scripts/gen-whitebox-menu-catalog.mjs

This command, referenced in [packages/processing/src/wasm-convert.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-convert.ts), scans the Whitebox-Next-Gen WebAssembly toolbox and generates the searchable tool catalog.

Test Commands

Quality assurance spans frontend, backend, and end-to-end suites as defined in [.github/workflows/ci.yml](https://github.com/opengeos/GeoLibre/blob/main/.github/workflows/ci.yml).

Frontend Testing

# Run Vitest unit tests for all packages

npm run test:frontend

# Run with coverage report

npm run test:frontend -- --coverage

Backend Testing

# Run Python FastAPI sidecar tests

npm run test:backend

# Or directly with pytest

cd backend/geolibre_server && pytest

Tests for the Python sidecar in [backend/geolibre_server/app/main.py](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/app/main.py) verify vector and raster endpoints.

End-to-End Testing

# Run Playwright browser tests

npx playwright test

# Run specific test file

npx playwright test tests/e2e/map-interactions.spec.ts

Tauri Desktop Commands

The desktop application in apps/geolibre-desktop uses the Tauri CLI for cross-platform native builds.

Development

# Start Tauri development window with Rust hot-reload

npm run tauri dev

# From the app directory

cd apps/geolibre-desktop && npm run tauri dev

Building Installers

# Build for current platform

npm run tauri build

# Build with specific target

npm run tauri build -- --target aarch64-apple-darwin

Supported platforms include Android, iOS, Windows, macOS, and Linux. The Tauri configuration in [apps/geolibre-desktop/vite.config.ts](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/vite.config.ts) integrates native file dialogs and platform-specific assets.

Python Sidecar Commands

The optional FastAPI backend provides extended processing capabilities.

Environment Setup

# Create virtual environment

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install with extras

pip install -e ".[vector,raster]"

Running the Server

# Start development server with auto-reload

uvicorn geolibre_server.app.main:app --reload --port 8000

# Production server

gunicorn geolibre_server.app.main:app -w 4 -k uvicorn.workers.UvicornWorker

Workspace-Specific Commands

Individual packages expose specialized scripts.

Core Package

# Build core state management

cd packages/core && npm run build

# Type-check the store implementation

cd packages/core && npx tsc --noEmit

The Zustand store in [packages/core/src/store.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) powers all application state.

Map Package

# Build MapLibre integration layer

cd packages/map && npm run build

Embed Package

# Build Jupyter embeddable bundle

cd packages/embed && npm run build

# Build browser extension

cd extensions/geolibre-chrome && npm run build

The embed package from [packages/embed/src/index.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/embed/src/index.ts) creates distributable artifacts for notebook integration.

Linting and Formatting

# Run ESLint across all packages

npm run lint

# Auto-fix issues

npm run lint -- --fix

# Format with Prettier

npm run format

CI Pipeline Commands

The GitHub Actions workflow in [.github/workflows/ci.yml](https://github.com/opengeos/GeoLibre/blob/main/.github/workflows/ci.yml) orchestrates:

1. Dependency installation — npm ci
2. Type checking — npx tsc --noEmit per package
3. Linting — npm run lint
4. Frontend tests — npm run test:frontend with coverage thresholds
5. Backend tests — npm run test:backend
6. E2E tests — npx playwright test
7. Rust checks — cargo check and cargo test for Tauri crate
8. Build verification — npm run build and npm run tauri build

Practical Command Sequences

Full Development Setup

# 1. Clone and enter repository

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

# 2. Install dependencies

npm install

# 3. Start development

npm run dev

# 4. In another terminal, start Taurus for desktop

npm run tauri dev

Adding a New Plugin

# 1. Create plugin directory

mkdir packages/plugins/src/plugins/my-plugin

# 2. Add plugin files (manifest.json, component, index.ts)

# 3. Register in usePlugins.ts

# Edit packages/plugins/src/hooks/usePlugins.ts

# 4. Test in development

npm run dev

# 5. Verify with lint and build

npm run lint && npm run build

Preparing a Release

# 1. Update version

npm version patch  # or minor/major

# 2. Regenerate processing catalog if needed

node scripts/gen-whitebox-menu-catalog.mjs

# 3. Run full test suite

npm run test:frontend && npm run test:backend && npx playwright test

# 4. Build all targets

npm run build

# 5. Build desktop installers

npm run tauri build

# 6. Verify artifacts in target/release/bundle/

Summary

• GeoLibre repository file system commands center on npm workspaces for dependency management and script orchestration
• Core development uses npm run dev for web and npm run tauri dev for desktop
• Testing splits across test:frontend, test:backend, and Playwright E2E suites
• Desktop packaging requires Tauri CLI commands for cross-platform installer generation
• Python sidecar operates through standard uvicorn/gunicorn commands with optional vector/raster extras
• CI pipeline enforces quality through type-checking, linting, coverage thresholds, and multi-platform builds

Frequently Asked Questions

What command starts GeoLibre in development mode?

Run npm run dev from the repository root to start the web development server with hot module replacement. For desktop development with native windowing, use npm run tauri dev which launches the Tauri application with Rust hot-reload enabled.

How do I build GeoLibre for production deployment?

Execute npm run build to generate production assets for web deployment. For desktop installers, run npm run tauri build which compiles platform-specific binaries for Windows, macOS, Linux, iOS, and Android through the configuration in apps/geolibre-desktop.

Where are the test commands defined in the GeoLibre repository?

Test commands are defined in the root package.json as npm run test:frontend for Vitest unit tests and npm run test:backend for Python pytest. The CI pipeline in .github/workflows/ci.yml orchestrates these with coverage enforcement and Playwright E2E validation.

Why does regenerating the Whitebox catalog require a separate Node script?

The gen-whitebox-menu-catalog.mjs script scans the WebAssembly toolbox at build time to generate a searchable JSON catalog of 1000+ geoprocessing tools. This decouples the tool metadata from runtime, improving startup performance in [packages/processing/src/wasm-convert.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-convert.ts).

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