{"id":45320,"library":"localforage-cordovasqlitedriver","title":"localForage-cordovaSQLiteDriver","description":"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).","status":"active","version":"1.8.0","language":"javascript","source_language":"en","source_url":"git://github.com/thgreasi/localForage-cordovaSQLiteDriver","tags":["javascript","localforage","SQLite","driver","cordova","typescript"],"install":[{"cmd":"npm install localforage-cordovasqlitedriver","lang":"bash","label":"npm"},{"cmd":"yarn add localforage-cordovasqlitedriver","lang":"bash","label":"yarn"},{"cmd":"pnpm add localforage-cordovasqlitedriver","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the driver to function.","package":"localforage","optional":false},{"reason":"Native SQLite plugin for Cordova; needed at runtime.","package":"cordova-sqlite-storage","optional":true}],"imports":[{"note":"The package needs to be imported as a namespace object (ESM) or via script tag as window.cordovaSQLiteDriver.","wrong":"const cordovaSQLiteDriver = require('localforage-cordovasqlitedriver');","symbol":"cordovaSQLiteDriver","correct":"import * as cordovaSQLiteDriver from 'localforage-cordovasqlitedriver';"},{"note":"The driver object must be passed; window.cordovaSQLiteDriver is only available when using <script> include.","wrong":"localforage.defineDriver(window.cordovaSQLiteDriver); // only works if included via script tag","symbol":"localforage.defineDriver","correct":"localforage.defineDriver(cordovaSQLiteDriver);"},{"note":"Use cordovaSQLiteDriver._driver as the driver name string, not a hardcoded literal.","wrong":"localforage.setDriver('cordovaSQLiteDriver'); // string not accepted; must use driver's _driver constant","symbol":"localforage.setDriver","correct":"localforage.setDriver([cordovaSQLiteDriver._driver, localforage.INDEXEDDB]);"}],"quickstart":{"code":"// In your Cordova app after onDeviceReady\nimport localforage from 'localforage';\nimport cordovaSQLiteDriver from 'localforage-cordovasqlitedriver';\n\n// Define and set the driver\nlocalforage.defineDriver(cordovaSQLiteDriver).then(() => {\n  return localforage.setDriver([\n    cordovaSQLiteDriver._driver,\n    localforage.INDEXEDDB,\n    localforage.WEBSQL\n  ]);\n}).then(() => {\n  // Now localforage uses SQLite on Cordova\n  return localforage.setItem('key', 'value');\n}).then((value) => {\n  console.log('Saved:', value);\n}).catch((err) => {\n  console.error('Driver setup failed:', err);\n});\n\n// For encrypted database (sqlcipher), pass dbKey in config:\nlocalforage.config({ dbKey: 'my-secret-key' });\n\n// Drop instance (v1.8+):\nlocalforage.dropInstance({ name: 'myDB' });","lang":"typescript","description":"Shows how to define and set the cordovaSQLiteDriver for localforage, including fallback drivers and encryption support."},"warnings":[{"fix":"Set the location property in localforage.config() to the previous location value (0 for iOS <= 1.1). See the plugin's iCloud guide.","message":"The 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.","severity":"breaking","affected_versions":">=1.2"},{"fix":"Call localforage.defineDriver(cordovaSQLiteDriver) before localforage.setDriver().","message":"The driver object must be explicitly defined via localforage.defineDriver() before calling setDriver(). Forgetting this step will cause a runtime error: 'driver is not defined'.","severity":"gotcha","affected_versions":"all"},{"fix":"Use cordovaSQLiteDriver._driver as the first argument in setDriver() array.","message":"The driver name string is cordovaSQLiteDriver._driver, not 'cordovaSQLiteDriver'. Using a hardcoded string will fail silently and fall back to other drivers.","severity":"gotcha","affected_versions":"all"},{"fix":"Test on an emulator/device or mock the plugin in a browser environment.","message":"This 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure tsconfig.json has 'moduleResolution': 'node' or use the bundled types directly.","message":"v1.5 dropped @types; TypeScript definitions are now bundled within the package. TypeScript users not using module resolution may need to update tsconfig.json.","severity":"breaking","affected_versions":">=1.5"}],"env_vars":null,"search_vec":"'1.5.0':85 '2020':14 'add':46 'allow':17 'api':66 'app':8,76 'async':62 'avail':82 'bridg':59 'cadenc':94 'cordova':30,88,100 'cordova/ionic':7 'cordovasqlitedriv':3 'databas':24 'dbkey':50 'devic':27 'differenti':57 'driver':5,16,40,99 'dropinst':49 'enabl':70 'encrypt':52 'hybrid':74 'implement':41 'indexeddb':78 'inherit':37 'javascript':96 'key':56,64 'key-valu':63 'localforag':2,10,18,60,84,97 'localforage-cordovasqlitedriv':1 'low':92 'maintain':91 'may':79 'mobil':26,75 'nativ':22,68 'persist':71 'plugin':33,90 'reduc':43 'releas':13,93 'requir':83 'size':44 'sqlcipher':35 'sqlite':4,23,31,69,89,98 'stabl':11 'storag':32,72 'support':47 'type':55 'typescript':54,101 'use':9,20 'v1.8.0':12 'valu':65 'via':28 'websql':39 'year':95","created_at":"2026-06-07T12:54:26.563806+00:00","updated_at":"2026-06-07T12:54:26.563806+00:00","problems":[{"fix":"Add localforage.defineDriver(cordovaSQLiteDriver) before setDriver().","cause":"localforage.defineDriver() was not called before setDriver().","error":"Error: driver is not defined"},{"fix":"Use import * as cordovaSQLiteDriver from 'localforage-cordovasqlitedriver';","cause":"Importing the driver incorrectly (e.g., default import when namespace is required).","error":"cordovaSQLiteDriver is not a function"},{"fix":"Ensure the script is included after cordova.js and loaded in the correct order, or use module import.","cause":"The driver object is not properly initialized (possibly from a script tag where window.cordovaSQLiteDriver is not yet loaded).","error":"TypeError: cordovaSQLiteDriver._driver is undefined"},{"fix":"Add .catch(err => console.error(err)) to the promise chain.","cause":"Missing .catch() on promise chain; common when using setDriver() without error handling.","error":"LocalForage: The error handler is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/thgreasi/localForage-cordovaSQLiteDriver","github":"git://github.com/thgreasi/localForage-cordovaSQLiteDriver","docs":null,"changelog":null,"pypi":null,"npm":"localforage-cordovasqlitedriver","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}