Responsibilities of Each Package in the GeoLibre npm Workspaces Monorepo

The GeoLibre npm workspaces monorepo organizes functionality into eight distinct packages—@geolibre/core, @geolibre/map, @geolibre/ui, @geolibre/processing, @geolibre/plugins, @geolibre/embed, @geolibre/collab-core, and geolibre-desktop—that separate concerns across state management, mapping, UI components, geoprocessing, plugins, embedding, collaboration, and the desktop application shell.

GeoLibre is structured as an npm workspaces monorepo that partitions the codebase into discrete, versioned packages according to the architecture documentation. This architecture enables clear separation of concerns while allowing code reuse across the desktop, web, and Jupyter builds. Understanding the responsibilities of each package in the GeoLibre npm workspaces monorepo is essential for contributors extending the platform and developers embedding its capabilities.

Core Package Responsibilities

The monorepo groups related functionality into separate npm packages under the packages/ directory, with one application workspace in apps/. Each package encapsulates a distinct architectural layer as implemented in the opengeos/GeoLibre source code.

@geolibre/core: Domain Types and Global State

The @geolibre/core package serves as the single source of truth for the entire application. It provides domain types, the project JSON schema, and the global Zustand store that manages the canonical state for layers, styles, selections, and project metadata.

According to packages/core/src/index.ts, this package exports the useAppStore hook and type definitions consumed by all other workspace packages. The store implementation ensures that layer records, symbology, and application selections remain synchronized across the React component tree without importing UI or mapping logic.

@geolibre/map: MapLibre GL Lifecycle Management

The @geolibre/map package manages the MapLibre-GL lifecycle and handles synchronization between the global store and MapLibre sources and layers. It supports raster, vector, MBTiles, and tile-service integrations, including Cesium 3-D globe support via the MapController class.

Key files include packages/map/package.json and controller source files such as src/cesium-camera.ts. The MapController.syncLayers() method reads the current state from @geolibre/core and updates the map engine accordingly, bridging the gap between application state and rendering.

@geolibre/ui: Shared React Components

The @geolibre/ui package supplies shared UI primitives built in a shadcn-style component architecture. It exports reusable React components including dialogs, dropdowns, tables, and tooltips that ensure consistent styling across the application.

Located in packages/ui/, this package keeps presentation logic decoupled from business logic. Components are imported from packages/ui/src/index.ts and used throughout the desktop and web interfaces without pulling in mapping or processing dependencies.

@geolibre/processing: Client-Side Geoprocessing

The @geolibre/processing package registers client-side algorithms and the Whitebox-WASM toolbox. It exposes a catalog of processing tools accessible from the "Processing" menu, enabling raster analysis and vector operations directly in the browser.

This package is defined in packages/processing/package.json and provides the runTool() function for invoking specific algorithms. It extends the core capabilities without bloating the initial bundle, loading WebAssembly modules on demand when processing operations are requested.

@geolibre/plugins: Extension Interface

The @geolibre/plugins package defines the plugin interface and ships built-in extensions for specialized data formats. It includes plugins for NetCDF, raster symbology, Zarr time-axis support, Earth Engine integration, and Deck.gl layers.

Plugins register additional layer types and UI controls that extend core capabilities. The NetcdfPlugin.addLayer() method, for example, allows users to load multidimensional scientific datasets by encapsulating format-specific parsing logic separate from the core map renderer.

@geolibre/embed: Lightweight Embedding Client

The @geolibre/embed package implements a lightweight, dependency-free client for the iframe embed API. Published independently to npm, this package allows external sites to embed a GeoLibre map without importing the full application bundle.

The GeoLibreEmbed class provides a thin API for initializing embedded views. This separation ensures that third-party integrators receive only the necessary code for rendering maps, minimizing payload size for embedding scenarios.

@geolibre/collab-core: Real-Time Collaboration Protocol

The @geolibre/collab-core package supplies the collaboration protocol and validation utilities used by the real-time collaborative editing feature. It functions as a thin core that other packages can import without pulling in UI code.

This package handles room initialization and operational transformation logic. The initCollab() function establishes WebSocket connections and session management, enabling multiple users to edit projects simultaneously while keeping the collaboration logic isolated from React components.

geolibre-desktop: Desktop Application Shell

While not published as an npm package, the geolibre-desktop workspace in apps/geolibre-desktop/ composes the UI, Tauri shell, and desktop-specific I/O. It imports the above packages to build the native desktop application defined in apps/geolibre-desktop/package.json.

This workspace handles file system access through Tauri APIs and integrates the other packages into a standalone executable. It serves as the entry point that ties the monorepo together for the desktop distribution.

Layered Data Flow Architecture

Together these packages form a layered architecture that processes data from input to rendering:

1. Data entry – Add-Data dialogs, Tauri file-picker, or plugins create layer records.
2. Store – @geolibre/core holds the canonical state.
3. Map syncing – @geolibre/map reads the store and updates MapLibre (or Cesium) accordingly.
4. UI – @geolibre/ui renders controls that mutate the store.
5. Processing & plugins – @geolibre/processing and @geolibre/plugins add algorithmic and data-source capabilities on top of the core store.
6. Embedding – @geolibre/embed offers a thin API for external embedding scenarios.

This separation enables independent versioning, easier testing, and the ability to ship only the needed pieces to downstream consumers.

Working with the Packages

Below are minimal examples showing how each package is typically imported and used inside the application code.

Accessing the Global Store

import { useAppStore } from '@geolibre/core';

const layers = useAppStore(state => state.layers);

Syncing Map Layers

import { MapController } from '@geolibre/map';

const controller = new MapController(mapInstance);
controller.syncLayers(); // reads store and updates MapLibre

Using UI Components

import { Button } from '@geolibre/ui';

<Button onClick={() => console.log('clicked')}>Add Layer</Button>;

Running Geoprocessing Tools

import { runTool } from '@geolibre/processing';

runTool('hillshade', { input: geojsonLayer });

Adding Plugin Layers

import { NetcdfPlugin } from '@geolibre/plugins';

NetcdfPlugin.addLayer({ url: 'example.nc' });

Embedding Maps in Iframes

import { GeoLibreEmbed } from '@geolibre/embed';

const embed = new GeoLibreEmbed('#container', { projectUrl: '/myproject.json' });
embed.load();

Initializing Collaboration

import { initCollab } from '@geolibre/collab-core';

initCollab({ roomId: 'abc123' });

Key Source Files

The following files provide entry points for exploring implementation details:

• @geolibre/core: packages/core/package.json, packages/core/src/index.ts
• @geolibre/map: packages/map/package.json, controller source files such as src/cesium-camera.ts
• @geolibre/ui: packages/ui/package.json, packages/ui/src/index.ts
• @geolibre/processing: packages/processing/package.json
• @geolibre/plugins: packages/plugins/package.json
• @geolibre/embed: packages/embed/package.json
• @geolibre/collab-core: packages/collab-core/package.json
• geolibre-desktop: apps/geolibre-desktop/package.json

Summary

• The GeoLibre npm workspaces monorepo separates concerns across eight distinct packages to enable code reuse and independent versioning.
• @geolibre/core maintains the canonical Zustand store and domain types used by all other packages.
• @geolibre/map bridges the store with MapLibre-GL and Cesium rendering engines.
• @geolibre/ui provides shadcn-style React components decoupled from business logic.
• @geolibre/processing and @geolibre/plugins extend functionality through WebAssembly tools and format-specific extensions.
• @geolibre/embed and @geolibre/collab-core support specialized use cases (embedding and real-time collaboration) without dragging in the full application.
• The geolibre-desktop workspace composes these packages into a Tauri-based native application.

Frequently Asked Questions

What is the purpose of npm workspaces in the GeoLibre repository?

The npm workspaces configuration allows GeoLibre to manage multiple packages within a single repository while maintaining separate package.json files and versioning for each module. This setup enables developers to work on @geolibre/core, @geolibre/map, and other packages simultaneously with automatic symlinking of local dependencies, ensuring that changes in one package immediately reflect in dependent workspaces during development.

How does @geolibre/core differ from @geolibre/map?

@geolibre/core contains the global Zustand store, TypeScript interfaces, and JSON schemas that define the application state, but it contains no rendering logic. @geolibre/map imports the store from core and implements the MapController class to synchronize that state with MapLibre-GL or Cesium instances, handling the actual visualization of layers and camera movements.

Can I use @geolibre/embed without installing the full GeoLibre application?

Yes. The @geolibre/embed package is specifically designed as a lightweight, dependency-free client published to npm independently. External sites can install only this package to embed GeoLibre maps via iframes without pulling in the heavy dependencies required for the full desktop or web editing interface, significantly reducing bundle size for simple embedding scenarios.

Where is the desktop-specific file system logic implemented?

Desktop-specific I/O operations, such as native file pickers and local file system access, are implemented in the geolibre-desktop workspace located at apps/geolibre-desktop/. This workspace uses Tauri APIs to bridge JavaScript with native operating system capabilities, while the individual @geolibre/* packages remain platform-agnostic and unaware of whether they are running in a browser or desktop environment.

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