Installation

npm install @devioarts/capacitor-sqlite && npx cap sync installs the plugin and copies its native sources into your Capacitor project. Each platform has one extra step beyond that base install, covered below.

Web

The Web implementation uses @sqlite.org/sqlite-wasm with the OPFS backend, installed as a runtime dependency of this package — no separate install step.

OPFS requires the page to be served with cross-origin isolation headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

The plugin's own dev server (playground/vite.config.ts) sets these on both the Vite dev server and preview server:

const coiHeaders = {
  'Cross-Origin-Opener-Policy': 'same-origin',
  'Cross-Origin-Embedder-Policy': 'require-corp',
};

export default defineConfig(({ command }) => ({
  server: { headers: coiHeaders },
  preview: { headers: coiHeaders },
}));

Without these headers, SharedArrayBuffer is unavailable and the OPFS VFS cannot initialize. Call isAvailable() at startup rather than assuming Web support — ':memory:' databases still work even when OPFS is unavailable. The bundled OPFS VFS requires Safari 17 or later; older Safari versions are unsupported.

OPFS sync access handles are exclusive per file. Do not open the same persistent database from two tabs, windows, workers, or hot-reload survivors at once — the second context can fail writes with SQLITE_IOERR. Close the database, or reload the stale context, before continuing. ':memory:' databases are not affected.

iOS

No extra setup beyond npx cap sync — the plugin links against the system SQLite3 library. Minimum deployment target is iOS 15.

Android

No extra setup beyond npx cap sync. Minimum minSdkVersion is API 24; the plugin's own android/build.gradle declares this floor, so a consuming app's minSdkVersion must be at least 24.

Electron

Electron support requires Node's built-in node:sqlite module, available from Electron 40+ (Node 24+). electron is an optional peer dependency (peerDependenciesMeta.electron.optional: true) — pure iOS/Android/Web consumers are never warned about a missing Electron install.

Register the plugin in your Electron main process after app.whenReady():

// electron/src/index.ts
import { app } from 'electron';
import { CapacitorSqlite } from '@devioarts/capacitor-sqlite/electron';
import { pluginSettings } from '@devioarts/capacitor-sqlite/electron/settings';

const capacitorSqlite = new CapacitorSqlite();

// Release the worker thread (and let SQLite flush its WAL) before the process exits.
app.on('before-quit', () => {
  void capacitorSqlite.dispose();
});

import '@devioarts/capacitor-sqlite/electron/settings' wires the plugin into Capacitor's Electron tooling so the standard Capacitor bridge can reach it; use this unless you are exposing CapacitorSqlite through custom IPC.

CapacitorSqlite lazily spawns a dedicated worker_threads worker on first use, so synchronous node:sqlite work never blocks Electron's main process, and keeps that worker alive for the life of the process. dispose() is not part of the shared CapacitorSqlitePlugin interface — it is an Electron-only addition. Call it explicitly (typically from app.on('before-quit')) to terminate the worker; a later plugin call automatically spawns a fresh worker on demand, so dispose() also doubles as recovery if a worker gets stuck.

Databases are stored by default at app.getPath('userData')/CapacitorSQLite/<name>.db.

If your build bundles the Electron main process (esbuild/rollup/webpack), ship @devioarts/capacitor-sqlite as a runtime dependency rather than inlining it — the plugin resolves its worker file via require.resolve('@devioarts/capacitor-sqlite/electron/worker') at runtime, and bundling relocates __dirname away from node_modules.

Verify the install

npm run verify

runs the build/verify steps for all four targets in the plugin's own repo (verify:ios, verify:android, verify:web, verify:electron). In a consuming app, the equivalent check is building for each target platform you ship and calling isAvailable() at runtime — see Quick start.

Next step

Concepts explains the mental model — result shapes, migrations, and transaction scoping — before you write application code.