How GeoLibre's Client-Side Whitebox WASM Geoprocessing Toolbox Enables Serverless Operations

GeoLibre's Whitebox WASM geoprocessing toolbox compiles the full WhiteboxTools engine into a ~5MB WebAssembly module that runs entirely in the browser, eliminating the need for Python sidecars or remote servers to perform complex geoprocessing tasks.

The opengeos/GeoLibre project transforms traditional GIS workflows by embedding a complete geoprocessing engine directly into the browser. Through the client-side Whitebox WASM geoprocessing toolbox, the application executes over 733 raster and vector analysis tools within the browser's sandbox, enabling true serverless deployment on static hosts like GitHub Pages or CDNs without any backend infrastructure.

Core Architecture Components

The WASM Engine Bundle (geolibre-wasm/tools)

At the heart of the serverless architecture lies the geolibre-wasm/tools package. This WASI-based WebAssembly bundle contains the wbtools_oss engine—the open-source WhiteboxTools—alongside GeoLibre-authored extensions. Compiled to a single ~5MB WASM module, this bundle requires no native binaries or Python processes. All algorithms execute within the browser's JavaScript runtime, making the entire toolchain available client-side.

The Client API (packages/processing/src/wasm-client.ts)

The wasm-client.ts file exposes the public API for interacting with the toolbox. Key functions include:

• whiteboxWasmAvailable() – Detects whether the WASM bundle can load in the current environment.
• listWhiteboxWasmTools() – Returns the complete catalog of approximately 733 tools from the bundled manifest.
• runWhiteboxWasmTool() – Executes specific tools via thin wrappers around the WASI runTool function.

The module uses lazy loading via import("geolibre-wasm/tools"), ensuring the heavy ~5MB runtime fetches only when a user initiates geoprocessing, keeping initial page loads lightweight.

Web Worker Isolation (packages/processing/src/wasm-convert.worker.ts)

Heavy geoprocessing operations run inside wasm-convert.worker.ts, a dedicated Web Worker that isolates computation from the main UI thread. This architecture guarantees responsive interfaces while executing intensive raster conversions or vector analyses, maintaining performance without server round-trips.

Sidecar Compatibility Layer (packages/processing/src/sidecar-client.ts)

The sidecar-client.ts module provides a compatibility layer that mirrors the FastAPI sidecar's JSON schema. This design allows UI components to function identically whether using the WASM runner or falling back to the Python sidecar. The fallback triggers only for datasets exceeding WebAssembly's ~4GiB memory limit, ensuring the client-side Whitebox WASM geoprocessing toolbox remains the primary serverless pathway.

Serverless Execution Workflow

Tool Discovery via Manifests

Each tool exposes a ToolManifest interface describing parameters, defaults, and source information. The UI components, such as those in apps/geolibre-desktop/src/components/processing/ProcessingDialog.tsx, generate forms directly from these manifests. Because manifests ship with the WASM bundle, the application requires no server-side lookups to present tool options.

Client-Side Processing

When a user executes a tool, runWhiteboxWasmTool invokes the WASI environment inside the browser. The function accepts tool IDs, argument arrays, and input files as Uint8Array buffers, then returns exit codes, stdout streams, and generated output files—all within the client sandbox.

Output Handling and Deep-Linking

Output processing occurs entirely client-side:

• Vector outputs use VECTOR_OUTPUT_EXTENSION mapping and zipShapefileSidecars to bundle multi-file Shapefiles into downloadable zip archives.
• Raster outputs convert to Cloud-Optimized GeoTIFFs for immediate browser download.
• Deep-linking functions (whiteboxToolFromLocation, whiteboxToolUrl in apps/geolibre-desktop/src/lib/whitebox-tool-url.ts) parse URL query strings like ?tool=<id> to pre-select tools without server contact.

Practical Implementation

The following TypeScript example demonstrates detecting, listing, and running tools using the client-side API:

// Check if the WASM toolbox is available
import { whiteboxWasmAvailable } from "packages/processing/src/wasm-client";

if (await whiteboxWasmAvailable()) {
  console.log("WASM toolbox ready – no server needed!");
}

// List all available Whitebox tools
import { listWhiteboxWasmTools } from "packages/processing/src/wasm-client";

const toolIds = await listWhiteboxWasmTools();
console.log("Available tools:", toolIds.slice(0, 5));

// Run the slope tool on an in-memory raster
import { runWhiteboxWasmTool } from "packages/processing/src/wasm-client";

const rasterBytes = await fetch("my-dem.tif").then(r => r.arrayBuffer());
const result = await runWhiteboxWasmTool("slope", {
  args: ["-i", "input.tif", "-o", "output.tif"],
  input: { "input.tif": new Uint8Array(rasterBytes) },
});

if (result.exitCode === 0) {
  const blob = new Blob([result.files["output.tif"]], { type: "image/tiff" });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = "slope.tif";
  a.click();
}

This implementation highlights lazy loading through whiteboxWasmAvailable, tool discovery via listWhiteboxWasmTools, and serverless execution with runWhiteboxWasmTool, returning files that users save locally without network transmission.

Summary

• GeoLibre's client-side Whitebox WASM geoprocessing toolbox packages the WhiteboxTools engine as a ~5MB WASI-compliant WebAssembly module, enabling complete browser-based geoprocessing.
• The architecture in packages/processing/src/wasm-client.ts provides lazy-loaded access to 733+ tools via whiteboxWasmAvailable, listWhiteboxWasmTools, and runWhiteboxWasmTool.
• Web Workers (wasm-convert.worker.ts) isolate heavy computations to maintain UI responsiveness during complex analyses.
• A compatibility layer (sidecar-client.ts) allows seamless fallback to Python sidecars only when datasets exceed the ~4GiB WASM memory limit.
• Tool manifests enable dynamic UI generation in ProcessingDialog.tsx, while output handlers manage vector zipping and raster conversion entirely within the browser.
• Deep-linking support via whiteboxToolUrl allows tool-specific URLs without server coordination, supporting static hosting on GitHub Pages or CDNs.

Frequently Asked Questions

What makes the Whitebox WASM toolbox "serverless"?

The toolbox compiles the entire WhiteboxTools engine to WebAssembly, allowing all 733+ geoprocessing functions to execute within the browser's sandbox. Because processing occurs entirely on the client using the geolibre-wasm/tools bundle, GeoLibre requires no Python backend, remote API, or server infrastructure—enabling deployment as a static website while maintaining full GIS capabilities.

How does GeoLibre handle large datasets that exceed browser memory limits?

When datasets approach WebAssembly's ~4GiB memory ceiling, packages/processing/src/wasm-convert.ts automatically routes requests to the Python sidecar via sidecar-client.ts. This compatibility layer mirrors the WASM API, allowing the same UI components to process massive datasets server-side while smaller jobs remain client-side, creating a hybrid serverless architecture.

Can users share direct links to specific Whitebox tools?

Yes. The whiteboxToolFromLocation function in apps/geolibre-desktop/src/lib/whitebox-tool-url.ts parses URL parameters (e.g., ?tool=slope) to pre-select and configure specific Whitebox tools. Because tool manifests ship with the client bundle, these deep-links work entirely offline or on static hosts without requiring server-side routing or database queries.

What file formats does the client-side toolbox support for output?

The toolbox handles multiple geospatial formats natively. Raster outputs convert to Cloud-Optimized GeoTIFFs for efficient browser rendering, while vector outputs use VECTOR_OUTPUT_EXTENSION mapping and zipShapefileSidecars to bundle Shapefile components into single zip downloads. All format conversions occur client-side using JavaScript libraries, maintaining the serverless workflow.

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