Registry / storage / localforage-cordovasqlitedriver

localforage-cordovasqlitedriver

library1.8.0jsnpmunverified

SQLite driver for Cordova/ionic apps using localForage (stable v1.8.0, released 2020). This driver allows localForage to use the native SQLite databases on mobile devices via the Cordova SQLite storage plugin (or sqlcipher). It inherits the WEBSQL driver implementation to reduce size and adds support for dropInstance(), dbKey for encryption, and TypeScript typings. Key differentiators: it bridges localForage's async key-value API to native SQLite, enabling persistent storage in hybrid mobile apps where IndexedDB may not be available. Requires localForage >= 1.5.0 and a Cordova SQLite plugin. Maintained, low release cadence (~yearly).

storage

npm install localforage-cordovasqlitedriver

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOCALFORAGE-CORDOV

localforage-cordovasqlitedriver

storagejavascriptv1.8.0

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.

cordovaSQLiteDriver

✓ import * as cordovaSQLiteDriver from 'localforage-cordovasqlitedriver';

✗ const cordovaSQLiteDriver = require('localforage-cordovasqlitedriver');

The package needs to be imported as a namespace object (ESM) or via script tag as window.cordovaSQLiteDriver.

localforage.defineDriver

✓ localforage.defineDriver(cordovaSQLiteDriver);

✗ localforage.defineDriver(window.cordovaSQLiteDriver); // only works if included via script tag

The driver object must be passed; window.cordovaSQLiteDriver is only available when using <script> include.

localforage.setDriver

✓ localforage.setDriver([cordovaSQLiteDriver._driver, localforage.INDEXEDDB]);

✗ localforage.setDriver('cordovaSQLiteDriver'); // string not accepted; must use driver's _driver constant

Use cordovaSQLiteDriver._driver as the driver name string, not a hardcoded literal.

Shows how to define and set the cordovaSQLiteDriver for localforage, including fallback drivers and encryption support.

// In your Cordova app after onDeviceReady import localforage from 'localforage'; import cordovaSQLiteDriver from 'localforage-cordovasqlitedriver'; // Define and set the driver localforage.defineDriver(cordovaSQLiteDriver).then(() => { return localforage.setDriver([ cordovaSQLiteDriver._driver, localforage.INDEXEDDB, localforage.WEBSQL ]); }).then(() => { // Now localforage uses SQLite on Cordova return localforage.setItem('key', 'value'); }).then((value) => { console.log('Saved:', value); }).catch((err) => { console.error('Driver setup failed:', err); }); // For encrypted database (sqlcipher), pass dbKey in config: localforage.config({ dbKey: 'my-secret-key' }); // Drop instance (v1.8+): localforage.dropInstance({ name: 'myDB' });

Debug

Known issues

breakingThe default storage location for SQLite changed in v1.2. Upgrading from <1.2 to >=1.2 may cause data loss on iOS if the location property is not updated.

fix

Set the location property in localforage.config() to the previous location value (0 for iOS <= 1.1). See the plugin's iCloud guide.

affects: >=1.2

gotchaThe driver object must be explicitly defined via localforage.defineDriver() before calling setDriver(). Forgetting this step will cause a runtime error: 'driver is not defined'.

fix

Call localforage.defineDriver(cordovaSQLiteDriver) before localforage.setDriver().

affects: all

gotchaThe driver name string is cordovaSQLiteDriver._driver, not 'cordovaSQLiteDriver'. Using a hardcoded string will fail silently and fall back to other drivers.

fix

Use cordovaSQLiteDriver._driver as the first argument in setDriver() array.

affects: all

gotchaThis driver only works inside a Cordova WebView on a device with the SQLite plugin installed. Running in a regular browser will error or fallback to IndexedDB/WebSQL.

fix

Test on an emulator/device or mock the plugin in a browser environment.

affects: all

breakingv1.5 dropped @types; TypeScript definitions are now bundled within the package. TypeScript users not using module resolution may need to update tsconfig.json.

fix

Ensure tsconfig.json has 'moduleResolution': 'node' or use the bundled types directly.

affects: >=1.5

Errors

Common errors & fixes

Error: driver is not defined

localforage.defineDriver() was not called before setDriver().

fix

Add localforage.defineDriver(cordovaSQLiteDriver) before setDriver().

cordovaSQLiteDriver is not a function

Importing the driver incorrectly (e.g., default import when namespace is required).

fix

Use import * as cordovaSQLiteDriver from 'localforage-cordovasqlitedriver';

TypeError: cordovaSQLiteDriver._driver is undefined

The driver object is not properly initialized (possibly from a script tag where window.cordovaSQLiteDriver is not yet loaded).

fix

Ensure the script is included after cordova.js and loaded in the correct order, or use module import.

LocalForage: The error handler is not a function

Missing .catch() on promise chain; common when using setDriver() without error handling.

fix

Add .catch(err => console.error(err)) to the promise chain.

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

localforagerequiredPeer dependency required for the driver to function.

cordova-sqlite-storageoptionalNative SQLite plugin for Cordova; needed at runtime.

Agent activity

21 hits · last 30 days

node

Resources

githubgit://github.com/thgreasi/localForage-cordovaSQLiteDriver ↗

packagelocalforage-cordovasqlitedriver ↗

homepagehttps://github.com/thgreasi/localForage-cordovaSQLiteDriver ↗