wa-spatialite

SpatiaLite (GEOS + PROJ) built into wa-sqlite as one WebAssembly module. Use SQLite in the browser or a worker with SpatiaLite SQL and geometry functions.

Installation

npm install wa-spatialite wa-sqlite

Install wa-sqlite as well — it provides Factory and the JS API used in Usage below.

Usage

1. WASM bundle — import the Emscripten factory from this package (default is the sync build). Subpaths wa-spatialite/sync, wa-spatialite/async, and wa-spatialite/jspi select the matching .mjs / .wasm pair (see package.json exports). Use locateFile if assets are not beside the script.
2. JS API — install wa-sqlite and import * as SQLite from "wa-sqlite" (or import vendor/wa-sqlite/src/sqlite-api.js when working inside this repo).
3. core_init — after await createModule({ … }), call module.ccall("core_init", "number", ["string"], [""]) once and check the return code is 0 (or SQLITE_OK from the API module). This registers SpatiaLite; skip it and spatial functions will not be available.

Example (Vite-style ?url imports; adjust paths for your bundler):

import * as SQLite from "wa-sqlite";
import mjsUrl from "wa-spatialite/wa-sqlite.mjs?url";
import wasmUrl from "wa-spatialite/wa-sqlite.wasm?url";

const { default: createModule } = await import(mjsUrl);
const module = await createModule({
  locateFile: (path) => (path.endsWith(".wasm") ? wasmUrl : path),
});

const rc = module.ccall("core_init", "number", ["string"], [""]);
if (rc !== SQLite.SQLITE_OK) throw new Error(`core_init failed: ${rc}`);

const sqlite3 = SQLite.Factory(module);
const db = await sqlite3.open_v2(":memory:");
await sqlite3.exec(db, "SELECT spatialite_version();", (row, cols) => {
  console.log(cols, row);
});
await sqlite3.close(db);

Setup

git clone https://github.com/Tom-Alexander/wa-spatialite wa-spatialite && cd wa-spatialite
git submodule update --init --recursive

Vendored code lives under vendor/ (wa-sqlite, libspatialite, GEOS, PROJ).

Build WASM

Needs: Emscripten (emcc, emcmake, emmake, …), cmake, make, python3, curl, openssl, and a sqlite3 CLI on PATH (PROJ builds proj.db with it).

make wasm-spatialite-sync

Writes dist/wa-sqlite.mjs and dist/wa-sqlite.wasm. For all variants (sync, Asyncify, JSPI): make or make wasm-spatialite. Clean: make clean-wasm.

libspatialite is built with a minimal feature set (GeoPackage, RTTOPO, and several optional deps are off). Turn more on only if you add WASM-capable dependencies and adjust configure.

Demo

Requires a finished build so dist/ has the .mjs / .wasm files.

make wasm-spatialite-sync   # if dist/ is empty
npm install && npm run demo

Dev server: http://localhost:8080 (see vite.config.ts). Production: npx vite build, then npm run demo:preview.