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

> Discover how GeoLibre's client-side Whitebox WASM toolbox enables serverless geoprocessing, running complex tasks entirely in the browser without remote servers.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: internals
- Published: 2026-08-03

---

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

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

Heavy geoprocessing operations run inside [`wasm-convert.worker.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts))

The [`sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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:

```typescript
// 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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-client.ts) provides lazy-loaded access to 733+ tools via `whiteboxWasmAvailable`, `listWhiteboxWasmTools`, and `runWhiteboxWasmTool`.
- Web Workers ([`wasm-convert.worker.ts`](https://github.com/opengeos/GeoLibre/blob/main/wasm-convert.worker.ts)) isolate heavy computations to maintain UI responsiveness during complex analyses.
- A compatibility layer ([`sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-convert.ts) automatically routes requests to the Python sidecar via [`sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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.