Registry / database / react-indexed-db-hook

react-indexed-db-hook

JSON →
library1.0.14jsnpmunverified

The `react-indexed-db-hook` package provides a React hook-based abstraction over the browser's native IndexedDB API. It simplifies common database operations like initializing the database, creating object stores, and performing CRUD operations (add, get, update, delete) within React components. The current stable version is 1.0.14, last published over three years ago, indicating a slower release cadence, likely in maintenance mode rather than active development with new features. It aims to make the powerful, asynchronous, and transactional IndexedDB API more accessible to React developers, offering a more robust client-side storage solution than `localStorage` for larger, structured datasets, and enabling offline-first application capabilities.

npm install react-indexed-db-hook
INSTALL
IMPORT
SIG · REACT-INDEXED-DB-H
R
react-indexed-db-hook
databasejavascriptv1.0.14
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

initDB
✓ import { initDB } from 'react-indexed-db-hook';
✗ import initDB from 'react-indexed-db-hook';
Used once at application startup to configure IndexedDB database name, version, and object stores (schemas). It is a named import.
useIndexedDB
✓ import { useIndexedDB } from 'react-indexed-db-hook';
✗ import useIndexedDB from 'react-indexed-db-hook';
The primary React hook for interacting with a specific IndexedDB object store. It provides methods for CRUD operations.
DBConfig
✓ import type { DBConfig } from 'react-indexed-db-hook';
Type definition for the database configuration object passed to `initDB`.

Demonstrates initializing the IndexedDB database, adding a new user to an object store, and retrieving all users using the `useIndexedDB` hook. This covers basic setup and CRUD operations.

import React, { useEffect, useState } from 'react'; import { initDB, useIndexedDB } from 'react-indexed-db-hook'; interface User { id?: number; name: string; email: string; } // 1. Define your database configuration const dbConfig = { name: 'MyDatabase', version: 1, objectStoresMeta: [ { store: 'users', storeConfig: { keyPath: 'id', autoIncrement: true }, storeSchema: [ { name: 'name', keypath: 'name', options: { unique: false } }, { name: 'email', keypath: 'email', options: { unique: true } }, ], }, ], }; // 2. Initialize the database (typically once in your app's entry point) initDB(dbConfig); function UserForm() { const { add, getAll } = useIndexedDB<User>('users'); const [name, setName] = useState(''); const [email, setEmail] = useState(''); const [users, setUsers] = useState<User[]>([]); useEffect(() => { // Fetch all users on component mount getAll().then((data) => { setUsers(data); }); }, [getAll]); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); if (!name || !email) return; try { const userId = await add({ name, email }); alert(`User added with ID: ${userId}`); setName(''); setEmail(''); // Re-fetch users to update the list getAll().then((data) => setUsers(data)); } catch (error) { console.error('Error adding user:', error); alert('Failed to add user. Email might already exist.'); } }; return ( <div> <h1>Add New User</h1> <form onSubmit={handleSubmit}> <input type="text" placeholder="Name" value={name} onChange={(e) => setName(e.target.value)} /> <input type="email" placeholder="Email" value={email} onChange={(e) => setEmail(e.target.value)} /> <button type="submit">Add User</button> </form> <h2>Users List</h2> {users.length === 0 ? ( <p>No users yet.</p> ) : ( <ul> {users.map((user) => ( <li key={user.id}> {user.name} ({user.email}) </li> ))} </ul> )} </div> ); } export default UserForm;
Debug
Known issues
gotchaIndexedDB is a browser-only API. Using `react-indexed-db-hook` directly in Server-Side Rendering (SSR) environments (like Next.js or Astro) will result in `window is not defined` errors. Ensure IndexedDB-related code runs only on the client-side, typically by dynamically importing components or checking `typeof window !== 'undefined'`.
fix
Guard IndexedDB usage with client-side checks or dynamic imports for SSR applications. Example: `if (typeof window !== 'undefined') { // IndexedDB code }`.
affects: >=1.0.0
breakingChanging `keyPath` or adding new indexes to an existing object store requires incrementing the database version in `initDB`. Failure to do so will result in `DOMException: A mutation operation was attempted on a database that did not allow mutations` or `VersionError`.
fix
When modifying your `dbConfig` (e.g., changing `objectStoresMeta`), increment the `version` number in `initDB`. Handle schema migrations in the `onupgradeneeded` event if more complex logic is required (though this library abstracts some of that).
affects: >=1.0.0
gotchaIndexedDB operations can be 'blocked' if the database is open in other browser tabs or instances when an `onupgradeneeded` event is triggered. This can prevent schema changes or even database deletion.
fix
Inform users to close other tabs if they encounter 'blocked' errors during database upgrades or deletions. For critical updates, consider using `IDBFactory.deleteDatabase()` with `onblocked` handling, or implement a version migration strategy that gracefully handles conflicts.
affects: >=1.0.0
gotchaThe `react-indexed-db-hook` package has not been updated in over three years (last published 2022-11-27). While functional, it may not receive new features, performance optimizations, or prompt bug fixes compared to more actively maintained IndexedDB wrappers or state management libraries.
fix
Evaluate your project's needs for active maintenance and support. For long-term projects or those requiring advanced features, consider alternatives like `Dexie.js` or `RxDB` which provide more robust and actively developed abstractions over IndexedDB.
affects: >=1.0.0
Errors
Common errors & fixes
Failed to open IndexedDB: A mutation operation was attempted on a database that did not allow mutations.
Attempting to change database schema (e.g., add or modify an object store or index) without incrementing the database version in `initDB`.
fix
Increment the `version` property in your `dbConfig` object passed to `initDB` whenever you make schema changes to your `objectStoresMeta`.
Uncaught (in promise) DOMException: Failed to execute 'transaction' on 'IDBDatabase': The database is not running a versionchange transaction.
This often occurs when trying to perform write operations (add, put, delete) on IndexedDB outside of an active write transaction context, or when a transaction has already completed.
fix
Ensure that all write operations are performed within the scope of a transaction explicitly created for that purpose. The `useIndexedDB` hook is designed to manage these transactions, so this error might indicate incorrect usage of the hook's methods or an attempt to use IndexedDB directly without proper transaction handling.
ReferenceError: window is not defined
Attempting to run IndexedDB-related code, which is a browser API, in a Node.js environment (e.g., during Server-Side Rendering with Next.js or other SSR frameworks).
fix
Wrap your IndexedDB-dependent code in client-side checks (`if (typeof window !== 'undefined')`) or dynamically import components that use `react-indexed-db-hook` to ensure they only render in the browser.
Upgrade
Version history
1.0.14latest on npm
Audit
Dependencies
reactrequiredPeer dependency required for all React-based libraries.
react-domrequiredPeer dependency required for rendering React components.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
react-indexed-db-hook — npm install react-indexed-db-hook · libregistry