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

> Master GeoLibre repository file system commands. Learn npm workspace, Tauri CLI operations, and project structure for efficient development. Explore our comprehensive guide now.

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

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/package.json) defines the npm workspace structure.

### Installing Dependencies

```bash

# Install all dependencies across workspaces

npm install

# Clean install (recommended for CI)

npm ci

```

The root [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json) declares workspaces under `apps/*`, `packages/*`, `backend/*`, and `extensions/*`, allowing npm to hoist shared dependencies and link local packages automatically.

### Running Development Servers

```bash

# 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)](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

```bash

# 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)](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

```bash

# 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)](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)](https://github.com/opengeos/GeoLibre/blob/main/.github/workflows/ci.yml).

### Frontend Testing

```bash

# Run Vitest unit tests for all packages

npm run test:frontend

# Run with coverage report

npm run test:frontend -- --coverage

```

### Backend Testing

```bash

# 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)](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/app/main.py) verify vector and raster endpoints.

### End-to-End Testing

```bash

# 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

```bash

# 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

```bash

# 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)](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

```bash

# 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

```bash

# 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

```bash

# 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)](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) powers all application state.

### Map Package

```bash

# Build MapLibre integration layer

cd packages/map && npm run build

```

### Embed Package

```bash

# 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)](https://github.com/opengeos/GeoLibre/blob/main/packages/embed/src/index.ts) creates distributable artifacts for notebook integration.

## Linting and Formatting

```bash

# 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)](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

```bash

# 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

```bash

# 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

```bash

# 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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/.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)](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-convert.ts).