localForage — Offline Storage That Just Works

Introduction

localForage provides a simple key-value API modeled after localStorage but backed by IndexedDB or WebSQL for much higher storage limits and non-blocking reads and writes. It lets developers store blobs, typed arrays, and complex objects without serialization boilerplate, falling back gracefully across browsers.

What localForage Does

• Stores and retrieves JavaScript objects, blobs, and typed arrays with a promise-based API
• Automatically selects the best storage backend: IndexedDB, WebSQL, or localStorage
• Supports multiple named database instances for data isolation
• Provides iteration over all stored keys with a forEach method
• Works in all modern browsers and older ones back to IE 10

Architecture Overview

localForage wraps multiple browser storage engines behind a unified asynchronous interface. On initialization, it probes for the best available driver in order: IndexedDB, WebSQL, then localStorage. Each driver implements the same internal contract (getItem, setItem, removeItem, keys, iterate). Values are serialized only when falling back to localStorage; IndexedDB and WebSQL store structured clones natively, preserving types like Blob and ArrayBuffer without manual conversion.

Setup & Configuration

• Install from npm or include via CDN for direct browser use
• Import and use immediately; no configuration required for defaults
• Create isolated instances with localforage.createInstance({ name: 'myDB' })
• Force a specific driver with localforage.setDriver(localforage.INDEXEDDB)
• Configure database name, store name, and version via localforage.config()

Key Features

• Promise and callback API for flexible async patterns
• Stores binary data (Blob, File, ArrayBuffer) natively in IndexedDB
• Automatic driver selection with transparent fallback
• Multiple independent instances per application
• Tiny footprint (under 10 KB minified and gzipped)

Comparison with Similar Tools

• idb — thin IndexedDB wrapper with no fallback; localForage adds multi-driver support and a simpler API
• Dexie.js — full IndexedDB ORM with queries and indexes; localForage is simpler for basic key-value needs
• PouchDB — document database with CouchDB sync; heavier than localForage for simple caching
• localStorage (native) — synchronous and limited to 5 MB of strings; localForage removes both constraints

FAQ

Q: How much data can localForage store? A: When using IndexedDB (the default), browsers typically allow hundreds of megabytes. The exact limit depends on the browser and available disk space.

Q: Does localForage work in Web Workers? A: Yes. IndexedDB is available in workers, so localForage functions normally in that context.

Q: Can I use localForage with React or Vue? A: Yes. It is framework-agnostic and works anywhere JavaScript runs in the browser.

Q: Is the data encrypted? A: No. localForage stores data as-is in the browser's storage. For encryption, wrap values with a library like crypto-js before storing.

Sources

• https://github.com/localForage/localForage
• https://localforage.github.io/localForage/