dexie

A Minimalistic Wrapper for IndexedDB

weekly downloads990K

versionv4.3.0

licenseApache-2.0

categorydatabase

indexeddbbrowserdatabase

Overview

Dexie is a lightweight JavaScript wrapper around IndexedDB that removes the complexity of the native API while maintaining its performance benefits. Instead of dealing with verbose transaction callbacks and event handlers, you get a promise-based interface with intuitive query methods and automatic transaction management. With nearly 1 million weekly downloads, it's trusted by production applications including WhatsApp Web.

The library exists because IndexedDB's native API is notoriously difficult to work with—requiring boilerplate for basic CRUD operations, manual transaction handling, and callback-based error management. Dexie provides a declarative schema definition system, chainable query methods, and reactive live queries that automatically update your UI when data changes. It's not trying to be a full ORM or replace server-side databases; it's focused on making browser-based structured storage practical.

Developers building progressive web apps, offline-first applications, or any browser-based tool that needs to store significant amounts of structured data will find Dexie essential. It's particularly valuable for dashboards with heavy client-side filtering, collaborative tools that need local caching, or mobile web apps that must function without connectivity. The optional Dexie Cloud addon extends this with real-time sync and authentication, but the core library works entirely client-side with no backend dependencies.

Dexie strikes a balance between simplicity and power. You get indexed queries, compound indexes, full-text search capabilities, and bulk operations that are optimized at the IndexedDB level. The API surface is small enough to learn quickly but expressive enough to handle complex data scenarios without dropping down to raw IndexedDB calls.

Quick Start

typescript

import { Dexie } from 'dexie';

// Define database schema
class TaskDatabase extends Dexie {
  tasks;
  
  constructor() {
    super('TaskDB');
    this.version(1).stores({
      tasks: '++id, title, status, dueDate, [status+dueDate]'
    });
    this.tasks = this.table('tasks');
  }
}

const db = new TaskDatabase();

// Bulk insert tasks
await db.tasks.bulkAdd([
  { title: 'Review PRs', status: 'pending', dueDate: '2024-01-15', tags: ['dev'] },
  { title: 'Write docs', status: 'pending', dueDate: '2024-01-16', tags: ['docs'] },
  { title: 'Deploy hotfix', status: 'completed', dueDate: '2024-01-14', tags: ['ops'] }
]);

// Query with compound index for efficient filtering
const urgentPending = await db.tasks
  .where('[status+dueDate]')
  .between(['pending', '2024-01-01'], ['pending', '2024-01-16'])
  .toArray();

console.log('Urgent tasks:', urgentPending);

// Update with partial changes
await db.tasks
  .where('status').equals('pending')
  .modify({ status: 'in-progress' });

// Live query for reactive UI (works with React/Vue/Svelte hooks)
const liveTasksObservable = db.liveQuery(() => 
  db.tasks.where('status').equals('in-progress').toArray()
);

liveTasksObservable.subscribe(tasks => {
  console.log('Active tasks updated:', tasks.length);
});

// Transaction for atomic multi-table operations
await db.transaction('rw', db.tasks, async () => {
  const task = await db.tasks.get(1);
  await db.tasks.update(1, { 
    status: 'completed',
    completedAt: new Date().toISOString()
  });
});

Use Cases

Offline-first note-taking or document editors: Store user documents locally with full-text search across content, automatic versioning through IndexedDB's object store capabilities, and instant filtering by tags or metadata. Changes sync when connectivity returns, and liveQuery() keeps the UI reactive across browser tabs.

E-commerce product catalogs with client-side filtering: Download thousands of products to IndexedDB on initial load, then provide instant search and faceted filtering without server round-trips. Compound indexes on category+price enable performant range queries, while bulk operations handle catalog updates efficiently.

Task management and project tracking tools: Store tasks, projects, and user data locally for instant load times and offline access. Use transactions to ensure related updates (like moving a task between projects) stay atomic, and leverage hooks to trigger side effects like updating cached aggregations.

Analytics dashboards caching API responses: Cache large datasets from backend APIs to provide instant visualization updates. Use Dexie's querying to slice data by date ranges or dimensions without re-fetching, and clear/refresh cache based on staleness policies.

Collaborative drawing or design tools: Store canvas states, version history, and user actions locally. Dexie Cloud's realm-based access control enables sharing artboards between team members with proper permissions, while local storage ensures the app remains responsive during complex operations.

Pros & Cons

Pros

+Promise-based API eliminates IndexedDB callback hell; works seamlessly with async/await and modern error handling patterns
+liveQuery() provides reactive data binding that automatically refreshes UI components across tabs without manual event wiring
+Compound indexes and query operators (between, startsWith, anyOf) make complex filtering efficient without loading entire datasets into memory
+Bulk operations are optimized at the IndexedDB level, handling thousands of inserts/updates significantly faster than individual calls
+Schema versioning system with migrations makes database evolution manageable as your application grows

Cons

−Bundle size around 20-50KB minified is overhead for simple key-value storage where idb-keyval or localStorage might suffice
−IndexedDB limitations still apply: no server-side querying, storage quotas vary by browser, and some mobile browsers have aggressive eviction policies
−Dexie Cloud requires paid subscription beyond free tier; self-hosted sync solutions require significant custom implementation
−Query performance degrades without proper indexes; developers must understand IndexedDB index mechanics to optimize complex queries
−Breaking changes in v5 (dropping default export) will require migration effort for existing codebases

Alternatives

pouchdbv9.0.0

PouchDB is a pocket-sized database

databasedbcouchdb

53K / week

Comparisons

dexie vs pouchdb

database

Install

bash

npm install dexie

bash

pnpm add dexie

bash

bun add dexie

Overview

Quick Start

typescript

import { Dexie } from 'dexie';

// Define database schema
class TaskDatabase extends Dexie {
  tasks;
  
  constructor() {
    super('TaskDB');
    this.version(1).stores({
      tasks: '++id, title, status, dueDate, [status+dueDate]'
    });
    this.tasks = this.table('tasks');
  }
}

const db = new TaskDatabase();

// Bulk insert tasks
await db.tasks.bulkAdd([
  { title: 'Review PRs', status: 'pending', dueDate: '2024-01-15', tags: ['dev'] },
  { title: 'Write docs', status: 'pending', dueDate: '2024-01-16', tags: ['docs'] },
  { title: 'Deploy hotfix', status: 'completed', dueDate: '2024-01-14', tags: ['ops'] }
]);

// Query with compound index for efficient filtering
const urgentPending = await db.tasks
  .where('[status+dueDate]')
  .between(['pending', '2024-01-01'], ['pending', '2024-01-16'])
  .toArray();

console.log('Urgent tasks:', urgentPending);

// Update with partial changes
await db.tasks
  .where('status').equals('pending')
  .modify({ status: 'in-progress' });

// Live query for reactive UI (works with React/Vue/Svelte hooks)
const liveTasksObservable = db.liveQuery(() => 
  db.tasks.where('status').equals('in-progress').toArray()
);

liveTasksObservable.subscribe(tasks => {
  console.log('Active tasks updated:', tasks.length);
});

// Transaction for atomic multi-table operations
await db.transaction('rw', db.tasks, async () => {
  const task = await db.tasks.get(1);
  await db.tasks.update(1, { 
    status: 'completed',
    completedAt: new Date().toISOString()
  });
});

Use Cases

Pros & Cons

Pros

+Promise-based API eliminates IndexedDB callback hell; works seamlessly with async/await and modern error handling patterns
+liveQuery() provides reactive data binding that automatically refreshes UI components across tabs without manual event wiring
+Compound indexes and query operators (between, startsWith, anyOf) make complex filtering efficient without loading entire datasets into memory
+Bulk operations are optimized at the IndexedDB level, handling thousands of inserts/updates significantly faster than individual calls
+Schema versioning system with migrations makes database evolution manageable as your application grows

Cons

−Bundle size around 20-50KB minified is overhead for simple key-value storage where idb-keyval or localStorage might suffice
−IndexedDB limitations still apply: no server-side querying, storage quotas vary by browser, and some mobile browsers have aggressive eviction policies
−Dexie Cloud requires paid subscription beyond free tier; self-hosted sync solutions require significant custom implementation
−Query performance degrades without proper indexes; developers must understand IndexedDB index mechanics to optimize complex queries
−Breaking changes in v5 (dropping default export) will require migration effort for existing codebases