spl.js

library1.0.1jsnpmunverified

spl.js bundles SpatiaLite 5.1.1-rc0 with SQLite 3.51.1, GEOS 3.14.1, PROJ 9.7.1, and rttopo 1.1.0 for spatial operations in Node.js (sync API) and browsers (async API). Released under ISC license, it provides a unified API for managing spatial databases, importing GeoPackage and Shapefile formats, and handling GeoJSON/JSON transparently. Key differentiators: includes a minimal proj.db for Web Mercator and UTM, supports custom extensions, and auto-detects JSON/GeoJSON bindings. The WASM binary is ~4.5MB gzipped and ships TypeScript definitions. Release cadence is ongoing with version 1.0.1 as of 2025.

database

npm install spl.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPL.JS

spl.js

databasejavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SPL

✓ import SPL from 'spl.js'

✗ const SPL = require('spl.js')

Default export is a factory function. ESM is needed for browser usage; in Node.js ESM is recommended, but CJS require works with default import interop.

spl.database

✓ const db = await spl.db()

✗ const db = spl.db

db() is an async method that returns a Database instance. Spl is obtained via SPL() factory.

db.exec

✓ const result = await db.exec('SELECT 1').get.first

✗ const result = db.exec('SELECT 1').get.first

exec() returns a promise; in browser (async API) you must await. In Node.js it's synchronous by default but can be awaited.

Shows how to initialize SPL, create an in-memory database, retrieve SpatiaLite version, and perform basic CRUD operations using prepared statements.

import SPL from 'spl.js'; async function main() { const spl = await SPL(); const db = await spl.db(); const version = await db.exec('SELECT spatialite_version()').get.first; console.log('SpatiaLite version:', version); await db.exec('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)'); await db.exec('INSERT INTO test VALUES (?, ?)', [1, 'hello']); const row = await db.exec('SELECT * FROM test').get.objs; console.log(row); } main().catch(console.error);

Debug

Known issues

gotchaBrowser requires WebWorker support; Firefox has a known issue with range requests on GitHub Pages that may cause downloads to fail.

fix

Use Chrome or Safari for examples hosted on GitHub Pages, or serve with correct Content-Encoding headers.

affects: >0

gotchaSpatiaLite 5.1.1-rc0 is a release candidate; some features may be experimental or incomplete.

fix

Check SpatiaLite changelog and test extensively before production use.

affects: 1.0.1

gotchaAuto JSON/GeoJSON parsing may cause unexpected type coercion. For example, POINT(0 0) becomes a GeoJSON object.

fix

Disable autoGeoJSON option or handle objects explicitly.

affects: >=1.0.0

gotchaNode.js API is synchronous but returns promises in browser. Mixing sync/async can cause confusion.

fix

Always use async/await for cross-platform compatibility.

affects: >0

gotchaFull PROJ database is not included by default; only minimal EPSG. You may need to mount and set custom proj.db.

fix

Use spl.fs.mount('proj', [...]) and call PROJ_SetDatabasePath('/proj/proj.db').

affects: 1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'spl.js'

Missing package installation or wrong import path.

fix

Run 'npm install spl.js' and ensure import uses 'spl.js' not 'spl'.

TypeError: spl.db is not a function

SPL() factory not awaited; spl is a Promise, not the SPL instance.

fix

Use 'const spl = await SPL()' before calling spl.db().

Error: Failed to decode downloaded array buffer

The WASM file download failed due to network or CORS issues.

fix

Ensure the server serves WASM with correct MIME type (application/wasm) and has CORS headers.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/jvail/spl.js ↗

packagespl.js ↗

homepagehttps://github.com/jvail/spl.js#readme ↗