React Hooks for Dexie.js

Common errors

• Error: Cannot find module 'dexie-react-hooks' or TypeError: Cannot read properties of undefined (reading 'useLiveQuery')

  cause The package is not installed, there's a wrong import path, or a CommonJS/ESM module mismatch.
  fix Ensure the package is installed with `npm install dexie-react-hooks dexie react react-dom`. Use `import { useLiveQuery } from 'dexie-react-hooks'` in an ESM-compatible environment, or configure your build system for CJS compatibility.

• useLiveQuery does not update when data changes

  cause The underlying Dexie operations are not correctly triggering reactivity, the query's dependency array is incorrect, or an outdated Dexie.js version is in use.
  fix Ensure all database modifications (add, put, delete, update) are done via Dexie's API. Check that your `dexie` package version is `>=4.0.9`. Verify the `useLiveQuery` dependency array includes all external variables used within the query function.

• TypeError: db.table.method is not a function (e.g. db.todos.toArray is not a function)

  cause The Dexie database instance or a specific table is not properly initialized, typed, or the database class is not correctly extending `Dexie`.
  fix Review your Dexie database schema definition, ensuring tables are correctly defined in `db.version().stores({})` and that the `db` instance is correctly created. For TypeScript, ensure proper typing for your database and its tables.

Warnings

• breaking Dexie.js v4.2.0-rc.1 and later introduced a significant change for Y.js users, moving `DexieYProvider` from the `dexie` package into a new `y-dexie` package. While `dexie-react-hooks`'s `useDocument` is related, users integrating Y.js must ensure both `dexie` and `y-dexie` dependencies are correctly installed and imported as per `dexie@4.2.0` and above.
  Fix: For Y.js integration, ensure `npm install y-dexie` and update `DexieYProvider` imports from `y-dexie` instead of `dexie`.
• gotcha This package has a peer dependency on `dexie` version `>=4.2.0-alpha.1 <5.0.0` and `react` version `>=16`. Using incompatible versions of `dexie` or `react` can lead to runtime errors, unexpected behavior, or broken reactivity due to API mismatches or internal inconsistencies.
  Fix: Always check your `dexie` and `react` versions and ensure they fall within the specified peer dependency ranges. Use `npm install` or `yarn install` to resolve peer dependencies automatically if your package manager supports it, or manually install compatible versions.
• gotcha `useLiveQuery` relies on Dexie's internal change tracking for reactivity. For optimal performance and correct re-renders, ensure that all database operations (add, put, delete, update) are performed exclusively through the Dexie instance (e.g., `db.table.method()`). Direct mutations via IndexedDB APIs will not trigger `useLiveQuery` updates.
  Fix: Always use Dexie's API methods for all database modifications. If you need to interact with IndexedDB directly, consider manually triggering a re-render or explicitly notifying `useLiveQuery` if possible.
• gotcha The dependency array for `useLiveQuery` (the second argument) should accurately reflect all external values that, if changed, would require re-executing the query function. An empty array `[]` means the query runs once and then re-subscribes only on database changes; if the query itself depends on component props or state, these must be included in the array to ensure correct reactivity.
  Fix: Review the variables used inside your `useLiveQuery` callback function. If any props or state variables are used, include them in the dependency array to ensure the query re-runs when those values change.

Install

• npm install dexie-react-hooks npm
• yarn add dexie-react-hooks yarn
• pnpm add dexie-react-hooks pnpm

Imports

• useLiveQuery
  wrong:

  const useLiveQuery = require('dexie-react-hooks').useLiveQuery

  correct:

  import { useLiveQuery } from 'dexie-react-hooks'

  Primary hook for reactive data fetching. Use named import in ESM environments.
• useDexie
  wrong:

  import Dexie from 'dexie-react-hooks'; // Incorrectly assuming a default export for the instance

  correct:

  import { useDexie } from 'dexie-react-hooks'

  Hook to access the Dexie database instance, typically used with a DexieProvider context.
• useDocument

  import { useDocument } from 'dexie-react-hooks'

  Hook introduced in v4.2.0 for Y.js integration, typically used in conjunction with dexie-cloud-addon and y-dexie.

Quickstart

Demonstrates how to define a Dexie database, create a React component, and use `useLiveQuery` to fetch and display data reactively, with add and toggle functionality.

import React from 'react';
import { useLiveQuery } from 'dexie-react-hooks';
import Dexie from 'dexie';

// Define your Dexie database schema and class
interface Todo {
  id?: number;
  title: string;
  completed: boolean;
}

class MyDatabase extends Dexie {
  todos!: Dexie.Table<Todo, number>;

  constructor() {
    super('MyTodoDatabase');
    this.version(1).stores({
      todos: '++id, title, completed'
    });
  }
}

// Instantiate the database
const db = new MyDatabase();

// React component using the useLiveQuery hook
const TodoList: React.FC = () => {
  // useLiveQuery subscribes to changes in db.todos
  const todos = useLiveQuery(
    () => db.todos.toArray(),
    [] // Empty dependency array means the query function is stable; re-queries on DB changes.
  );

  const addTodo = async () => {
    await db.todos.add({ title: `New Todo ${Date.now()}`, completed: false });
  };

  const toggleTodo = async (id: number) => {
    const todo = await db.todos.get(id);
    if (todo) {
      await db.todos.update(id, { completed: !todo.completed });
    }
  };

  if (!todos) return <div>Loading todos...</div>; // Data is null on first render until query resolves

  return (
    <div>
      <h1>My Todos</h1>
      <button onClick={addTodo}>Add Todo</button>
      <ul>
        {todos.map(todo => (
          <li key={todo.id}>
            <input
              type="checkbox"
              checked={todo.completed}
              onChange={() => toggleTodo(todo.id!)}
            />
            <span style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}>
              {todo.title}
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
};

export default TodoList;