wa-spatialite

SpatiaLite (with GEOS and PROJ) linked into wa-sqlite as a single WebAssembly module. SQLite runs in the browser or a worker with the same JS API as upstream wa-sqlite, plus SpatiaLite SQL and geometry functions.

What you get

• Static link: libspatialite, GEOS, PROJ, and zlib are compiled with Emscripten and linked into the wa-sqlite .mjs / .wasm outputs (no dynamic extension loading).
• Three builds: sync (wa-sqlite.mjs), Asyncify (wa-sqlite-async.mjs), and JSPI (wa-sqlite-jspi.mjs), matching upstream wa-sqlite.
• Bridge: src/spatialite_init.c registers SpatiaLite via sqlite3_auto_extension. You must call the exported core_init once after the module loads (see below).
• Demo: Vite dev server under demo/ that runs sample SpatiaLite SQL in the browser.

Prerequisites

Native / WASM build (make)

• Emscripten (emcc, em++, emcmake, emmake, emar)
• cmake, make, python3, curl, openssl
• A sqlite3 CLI on your PATH (PROJ’s build uses it to assemble proj.db)

Demo (npm run demo)

• Node.js 18+
• A completed WASM build so dist/wa-sqlite.mjs and dist/wa-sqlite.wasm exist

Clone

This repo uses submodules:

git clone <repo-url> wa-spatialite
cd wa-spatialite
git submodule update --init --recursive

Vendored trees include wa-sqlite, libspatialite, GEOS, and PROJ under vendor/.

Build (WASM)

From the repository root:

make wasm-spatialite-sync

Produces dist/wa-sqlite.mjs and dist/wa-sqlite.wasm (sync build with SpatiaLite).

Other useful targets:

| Target | Purpose | |--------|---------| | make / make wasm-spatialite | Sync + async + JSPI variants; copies all into ./dist/ | | make wasm-spatialite-sync | Sync only → ./dist/ | | make wasm-spatialite-async | Asyncify variant | | make wasm-spatialite-jspi | JSPI variant | | make wasm-geos | GEOS only → build/wasm/ | | make wasm-proj | PROJ only | | make wasm-libspatialite | libspatialite only | | make clean-wasm | Remove build/wasm, build/geos, build/proj, build/libspatialite, staging, etc. |

Intermediate install prefix: build/wasm/ (static libraries and headers).

libspatialite feature set

The Makefile configures a minimal libspatialite (fewer native dependencies): among other flags, libxml2, MiniZIP, FreeXL, iconv, GeoPackage, RTTOPO, and GCP are disabled. Enable more features only if you add the corresponding WASM-capable dependencies and adjust configure options.

Submodule caveats

• emconfigure does not forward PKG_CONFIG_PATH; the Makefile sets EM_PKG_CONFIG_PATH so sqlite3.pc is found.
• The libspatialite fork may ship configure / install-sh without execute bits; the Makefile runs chmod +x where needed.
• A stale gaiaconfig.h in the submodule can shadow the real configure output; the Makefile copies the generated header from the build tree after configure.

Using from JavaScript

1. Load the Emscripten factory (same pattern as wa-sqlite).
2. Instantiate the module; pass locateFile if your .wasm is not next to the .mjs.
3. Call core_init once (exported as _core_init / ccall('core_init', …)).
4. Build the JS API with Factory(module) from vendor/wa-sqlite/src/sqlite-api.js and open databases as usual.

Example (sync build, paths illustrative):

import * as SQLite from "./vendor/wa-sqlite/src/sqlite-api.js";
import mjsUrl from "./dist/wa-sqlite.mjs?url";   // or your bundler’s equivalent
import wasmUrl from "./dist/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 !== 0) throw new Error("core_init failed");

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);

The demo app uses Vite ?url imports so the bundle is not loaded from the public/ folder (which Vite reserves for non-imported static files).

Demo (web dev server)

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

Opens http://localhost:8080 (see vite.config.ts). The page runs sample SQL (spatialite_version, MakePoint, etc.) against an in-memory database.

Production build of the demo:

npm run demo    # optional: verify dev
npx vite build  # output under demo/dist/
npm run demo:preview

License

MIT (see LICENSE). Third-party code in vendor/ retains its own licenses.