sqlite-promiser

library1.0.2jsnpmunverified

Async SQLite WASM with OPFS persistence for frontend apps (React, Next.js, Vite). Version 1.0.2 uses @sqlite.org/sqlite-wasm (peer dependency ≥3.45.0-0) with OO API #1 in a dedicated worker, avoiding the deprecated Worker1 promiser. Supports OPFS for persistent storage when cross-origin isolated, with automatic fallback to in-memory. Ships TypeScript types and provides a Vite plugin. Requires COOP/COEP headers and correct worker asset copying.

database

npm install sqlite-promiser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLITE-PROMISER

sqlite-promiser

databasejavascriptv1.0.2

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.

createDatabase

✓ import { createDatabase } from 'sqlite-promiser'

✗ const createDatabase = require('sqlite-promiser')

ESM-only; no CommonJS support.

describeEnvironment

✓ import { describeEnvironment } from 'sqlite-promiser'

✗ import describeEnvironment from 'sqlite-promiser'

Named export, not default.

headersPresets

✓ import { headersPresets } from 'sqlite-promiser'

Use for COOP/COEP headers. Returns an object with requireCorp and credentialless.

type EnvInfo

✓ import type { EnvInfo } from 'sqlite-promiser'

✗ import { EnvInfo } from 'sqlite-promiser'

TypeScript type import; not a runtime value.

Creates a SQLite database, creates a table, inserts and queries rows, then closes connection.

import { createDatabase, describeEnvironment, headersPresets } from 'sqlite-promiser'; console.log(describeEnvironment()); const db = await createDatabase({ name: 'app', preferOpfs: true }); await db.exec(`CREATE TABLE IF NOT EXISTS todo (id INTEGER PRIMARY KEY, title TEXT)`); await db.run(`INSERT INTO todo (title) VALUES (?)`, ['Buy milk']); const rows = await db.all(`SELECT id, title FROM todo`); console.log(rows); await db.close();

Debug

Known issues

gotchaWorker files must be copied/served: sqlite-oo1-worker.js, sqlite3.wasm, sqlite3-opfs-async-proxy.js. Missing any file causes silent failure.

fix

Ensure all three files are in the same directory as the worker URL.

affects: >=1.0.0

breakingOPFS persistence requires cross-origin isolation (COOP/COEP headers). Without it, falls back to in-memory.

fix

Set headers: Cross-Origin-Opener-Policy: same-origin; Cross-Origin-Embedder-Policy: require-corp or credentialless.

affects: >=0.0.1

gotchaThe OPFS async proxy worker is nested inside the OO1 worker. If the proxy file is not served as a Worker (JavaScript MIME type), it fails opaquely.

fix

Serve sqlite3-opfs-async-proxy.js with Content-Type: text/javascript and same-origin.

affects: >=0.0.1

deprecatedThe old Worker1 promiser is not used; sqlite-promiser uses OO API #1 directly.

fix

Use createDatabase from sqlite-promiser instead of sqlite3Worker1Promiser.

affects: >=1.0.0

gotchaPeer dependency @sqlite.org/sqlite-wasm must be installed separately and version ≥3.45.0-0.

fix

Run: pnpm add @sqlite.org/sqlite-wasm

affects: >=1.0.0

breakingVite's asset handling may rewrite worker URLs. Use the provided Vite plugin to avoid 404s.

fix

Import and configure vitePlugin from 'sqlite-promiser/vite' in vite.config.ts.

affects: >=1.0.0

Errors

Common errors & fixes

Failed to create database: OPFS not available

Cross-origin isolation headers missing or OPFS unsupported.

fix

Set COOP/COEP headers: Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp or credentialless.

TypeError: Failed to fetch dynamically imported module

Worker file (sqlite-oo1-worker.js) not found or wrong MIME type.

fix

Copy sqlite-oo1-worker.js to public/ or configure Vite plugin.

Error: sqlite3 is not defined

@sqlite.org/sqlite-wasm not installed or incompatible version.

fix

Run: pnpm add @sqlite.org/sqlite-wasm@>=3.45.0-0

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

@sqlite.org/sqlite-wasmrequiredCore SQLite WASM module loaded via sqlite3InitModule()

reactoptionalPeer dependency for React integration (optional if not using React)

viteoptionalPeer dependency for Vite plugin (optional if not using Vite)

Agent activity

15 hits · last 30 days

node