Client-Side Storage Showdown: Dexie vs idb-keyval vs localForage

When your web app needs to store data locally — whether for offline support, performance caching, or user preferences — you quickly outgrow localStorage. It’s synchronous, size-limited, and blocks the main thread. The modern solution is IndexedDB, but its raw API is verbose and callback-heavy. That’s where libraries like dexie, idb-keyval, and localforage come in. They all wrap IndexedDB, but with very different philosophies. Let’s compare how they handle real-world tasks.

🗃️ Data Model: Structured Tables vs Flat Key-Value

dexie treats IndexedDB like a real database — with tables, schemas, and indexes.

• Define tables upfront with versioned schemas.
• Support for compound indexes, primary keys, and relations.
• Query using a fluent, promise-based API.

// dexie: Define a table with schema
import Dexie from 'dexie';

const db = new Dexie('MyApp');
db.version(1).stores({
  contacts: '++id, name, email', // auto-incrementing id, indexes on name/email
});

// Insert and query
await db.contacts.add({ name: 'Alice', email: 'alice@example.com' });
const matches = await db.contacts.where('name').startsWith('A').toArray();

idb-keyval offers zero structure — just a global key-value store.

• No tables, no schemas, no indexes.
• Keys are strings; values can be any serializable object.
• Only four methods: get, set, del, clear.

// idb-keyval: Simple key-value operations
import { get, set, del } from 'idb-keyval';

await set('user-token', 'abc123');
const token = await get('user-token');
await del('user-token');

localforage also uses a flat key-value model, but mimics the localStorage API.

• Keys are strings; values are arbitrary objects.
• Supports async/await or callbacks.
• Automatically falls back to WebSQL or localStorage if IndexedDB isn’t available.

// localforage: localStorage-like async API
import localforage from 'localforage';

await localforage.setItem('theme', 'dark');
const theme = await localforage.getItem('theme');
await localforage.removeItem('theme');

🔍 Query Capabilities: From None to Full SQL-Like Expressions

Only dexie supports rich querying.

• Filter by index ranges (between, above, startsWith).
• Combine conditions with and/or.
• Sort, limit, offset, and count results.

// dexie: Complex query
const recentActiveUsers = await db.users
  .where('lastActive')
  .above(Date.now() - 7 * 24 * 60 * 60 * 1000)
  .filter(user => user.status === 'active')
  .sortBy('name');

idb-keyval and localforage have no query API.

• To find data, you must retrieve everything and filter in JavaScript — inefficient for large datasets.
• Best practice: only store small, isolated values you access by known key.

// idb-keyval/localforage: No native query support
// You'd have to do this (not recommended for large data):
const allKeys = await localforage.keys();
const matching = [];
for (const key of allKeys) {
  const value = await localforage.getItem(key);
  if (value && value.category === 'urgent') matching.push(value);
}

🧱 Schema Management and Migrations

dexie includes built-in versioned schema migrations.

• Declare database versions and how to upgrade between them.
• Handle data transformation during upgrades.

// dexie: Schema migration
db.version(2).stores({
  contacts: '++id, name, email, phone', // added 'phone'
}).upgrade(tx => {
  return tx.table('contacts').toCollection().modify(contact => {
    contact.phone = null; // initialize new field
  });
});

idb-keyval and localforage have no concept of schema.

• Since they store unstructured key-value pairs, there’s nothing to migrate.
• If your app’s data format changes, you must handle backward compatibility manually (e.g., detect old formats at read time).

⚡ Performance and Concurrency

All three use asynchronous IndexedDB operations, so none block the main thread.

dexie supports explicit transactions for batch operations:

// dexie: Batch write in a single transaction
await db.transaction('rw', db.contacts, async () => {
  await db.contacts.add({ name: 'Bob' });
  await db.contacts.add({ name: 'Carol' });
});
// Both writes happen in one IndexedDB transaction

idb-keyval batches operations automatically under the hood when possible, but you can’t control transaction boundaries.

localforage does not group operations — each setItem is a separate IndexedDB transaction, which can be slower for bulk writes.

🔄 Observability and Reactivity

Only dexie provides live data observation:

// dexie: Watch for changes
db.contacts.hook('updating', (modifications, primaryKey, obj) => {
  console.log('Contact updated:', obj);
});

// Or observe queries reactively (with dexie-observable plugin)

idb-keyval and localforage offer no built-in change listeners. You’d need to layer your own event system or use external state management.

📦 Fallbacks and Browser Support

localforage stands out by automatically falling back to WebSQL or localStorage if IndexedDB is unavailable (e.g., in older browsers or private browsing modes with quota limits).

dexie and idb-keyval require IndexedDB and will fail if it’s not supported or disabled. This is usually fine in modern apps targeting current browsers, but worth noting for broad compatibility.

💡 Real-World Guidance

Use dexie if:

• You’re building an offline-first app with relational data (e.g., a note-taking app, CRM, or chat client).
• You need to run complex queries or sort/filter large datasets.
• You want to evolve your data model over time with safe migrations.

Use idb-keyval if:

• You only need to store a few simple values (e.g., auth tokens, UI settings, feature flags).
• You want the tiniest possible dependency with no setup.
• You don’t care about querying or structure.

Use localforage if:

• You’re replacing localStorage in an existing codebase and want minimal changes.
• You need fallback support for environments where IndexedDB might be restricted.
• Your data access patterns are strictly key-based with no need for queries.

📊 Summary Table

💬 Final Thought

These libraries solve different problems under the same umbrella. Don’t pick based on popularity — pick based on your data shape. If you’re storing more than a handful of independent values and ever need to “find” data rather than “look up” by key, dexie is worth the slight learning curve. For everything else, idb-keyval gives you the leanest path to async storage, while localforage eases legacy transitions.