Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createSQLiteThread
✓ import { createSQLiteThread } from 'sqlite-wasm-http';
✗ const { createSQLiteThread } = require('sqlite-wasm-http');
The library is ES6 module mode only; CommonJS imports will fail. Node.js 18+ is required for runtime features.
createHttpBackend
✓ import { createHttpBackend } from 'sqlite-wasm-http';
✗ const createHttpBackend = require('sqlite-wasm-http').createHttpBackend;
This is a named import from the ESM-only package. Attempting to use CommonJS `require()` will result in an error.
SQLite.SQLValue
✓ import type { SQLite } from 'sqlite-wasm-http';
// ... then use SQLite.SQLValue
Type imports are standard. The `SQLite` namespace exposes types like `SQLValue` and `SQLBindable` since v1.1.0 for improved TypeScript support.
This quickstart demonstrates how to initialize the HTTP VFS backend and connect to a remote MBTiles database. It then executes a simple query to list tables and count entries at a specific zoom level, showcasing basic database interaction and proper resource cleanup.
import { createSQLiteThread, createHttpBackend } from 'sqlite-wasm-http';
async function runRemoteQuery() {
const remoteURL = 'https://velivole.b-cdn.net/maptiler-osm-2017-07-03-v3.6.1-europe.mbtiles';
// createHttpBackend will autodetect if you can use SharedArrayBuffer or not
const httpBackend = createHttpBackend({
maxPageSize: 4096, // This is the current default SQLite page size
timeout: 10000, // 10s
cacheSize: 4096 // 4 MB (corresponds to 4096 pages of 1KB each for default 1024 page_size)
});
// Multiple DB workers can be created, all sharing the same backend cache
const db = await createSQLiteThread({ httpBackend });
try {
const results = await db.exec({
sql: 'SELECT name FROM sqlite_master WHERE type=\'table\';'
});
console.log('Tables:', results.results[0].row);
const countResult = await db.exec({
sql: 'SELECT count(*) FROM tiles WHERE zoom_level = ?;',
bind: [1]
});
console.log('Tiles at zoom 1:', countResult.results[0].row);
} finally {
db.close();
}
}
runRemoteQuery().catch(console.error);
Debug
Known issues
breakingThe library is strictly ES6 module mode only. CommonJS is not supported, including TypeScript transpiled to CommonJS. Projects must be configured to transpile to ES6 modules.fixEnsure your `tsconfig.json` `compilerOptions.module` is set to `ESNext` or `Node16` and your bundler/runtime environment supports ESM. Do not use `require()` statements.
affects: >=1.0.0
gotchaUsing the shared cache version with `SharedArrayBuffer` requires specific HTTP headers: `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`. Without these, shared cache will not function, and the library will fallback to a non-shared version.fixConfigure your web server to send `COOP: same-origin` and `COEP: require-corp` headers for the HTML page and JavaScript assets hosting the application. For local development, this may require specific server configurations or browser flags.
affects: >=1.0.0
gotchaFor optimal performance, especially with remote databases, it is highly recommended to set your SQLite database `page_size` to 1024 bytes and run `VACUUM` and `PRAGMA JOURNAL_MODE = DELETE;`.fixExecute `PRAGMA JOURNAL_MODE = DELETE; PRAGMA page_size = 1024; VACUUM;` on your SQLite database file. For FTS tables, also `INSERT INTO ftstable(ftstable) VALUES ('optimize');`. affects: >=1.0.0
breakingNode.js 18.19 introduced breaking changes that impacted integration tests. Users running specific Node.js 18.x versions might encounter unexpected behavior or require specific configurations.fixUpdate to Node.js 20+ or newer versions of Node.js 18.x that resolve the specific breaking changes mentioned (e.g., related to `ts-node` or Web Worker/Fetch API in Node.js). Ensure all dependencies are up to date.
affects: >=1.2.0 (integration tests affected), possibly earlier Node.js 18.x users
gotchaThe project is currently tagged as 'Experimental' in its README, indicating that while functional, its API or internal workings might undergo significant changes in future versions.fixBe aware that future major versions might introduce breaking changes. Monitor the GitHub repository for updates and release notes. Consider pinning to minor versions for production until it reaches a stable (non-experimental) status.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: SharedArrayBuffer is not defined
Attempting to use the shared cache backend in a browser environment without the necessary Cross-Origin Isolation headers (COOP/COEP) or in a Node.js environment that doesn't fully support Web Workers/SharedArrayBuffer.
fixFor browsers, ensure your server sends `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers. For Node.js, ensure you are running Node.js 18.x or higher, which provides built-in `web-worker` and `fetch` support. The library will attempt to fallback if these are not available.
TypeError: require is not a function
Trying to import `sqlite-wasm-http` using CommonJS `require()` syntax in an environment configured for ES modules, or in a project that needs to output ES modules.
fixRefactor your imports to use ES module syntax (e.g., `import { createSQLiteThread } from 'sqlite-wasm-http';`). If using TypeScript, ensure your `tsconfig.json` `compilerOptions.module` is set to `ESNext` or `Node16`. Error: Unknown module: sqlite3-worker1-promiser-node.mjs
This specific file (`sqlite3-worker1-promiser-node.mjs`) was eliminated in `v1.1.1` to reduce bundle size, indicating an outdated setup or caching issue if encountered on newer versions.
fixUpdate `sqlite-wasm-http` to at least `v1.1.1`. Clear your `node_modules` and package manager cache (`npm cache clean --force` or `pnpm store prune`). Ensure your bundler is resolving to the latest version.
Audit
Dependencies
No dependency data recorded yet.