ngx-indexed-db

library22.0.0jsnpmunverified

ngx-indexed-db is an Angular service that provides a reactive, observable-based wrapper around the browser's IndexedDB API. It simplifies database interactions for Angular applications, supporting both client-side rendering (CSR) and server-side rendering (SSR) since version 19.2.0. The current stable version is 22.0.0. While the exact release cadence isn't explicitly stated, the version numbers often align with Angular's major releases, suggesting active development. Key differentiators include its observable-driven API, full SSR compatibility, and the ability to provide custom IndexedDB implementations via an injection token for enhanced testing or non-browser environments. It also features a robust migration system for evolving database schemas.

database

npm install ngx-indexed-db

github ↗package ↗

INSTALL

IMPORT

SIG · NGX-INDEXED-DB

ngx-indexed-db

databasejavascriptv22.0.0

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.

NgxIndexedDBModule

✓ import { NgxIndexedDBModule } from 'ngx-indexed-db'

✗ const NgxIndexedDBModule = require('ngx-indexed-db')

Used for module-based Angular applications (e.g., in an NgModule's imports array).

DBConfig

✓ import { DBConfig } from 'ngx-indexed-db'

✗ import type { DBConfig } from 'ngx-indexed-db'

The interface for configuring your IndexedDB database schema and version.

provideIndexedDb

✓ import { provideIndexedDb } from 'ngx-indexed-db'

Recommended for standalone Angular applications or when using the providers array in an NgModule.

NgxIndexedDBService

✓ import { NgxIndexedDBService } from 'ngx-indexed-db'

The primary service injected into components/services to interact with the IndexedDB.

SERVER_INDEXED_DB

✓ import { SERVER_INDEXED_DB } from 'ngx-indexed-db'

An InjectionToken used to provide a custom IndexedDB implementation, primarily for SSR or testing environments.

This quickstart demonstrates configuring ngx-indexed-db for both NgModule and standalone Angular applications, including defining the database schema and implementing version migrations.

import { NgModule, ApplicationConfig } from '@angular/core'; import { NgxIndexedDBModule, provideIndexedDb, DBConfig } from 'ngx-indexed-db'; // Ahead of time compiles requires an exported function for factories export function migrationFactory() { return { 1: (db, transaction) => { const store = transaction.objectStore('people'); store.createIndex('country', 'country', { unique: false }); }, 3: (db, transaction) => { const store = transaction.objectStore('people'); store.createIndex('age', 'age', { unique: false }); } }; } const dbConfig: DBConfig = { name: 'MyDb', version: 3, objectStoresMeta: [{ store: 'people', storeConfig: { keyPath: 'id', autoIncrement: true }, storeSchema: [ { name: 'name', keypath: 'name', options: { unique: false } }, { name: 'email', keypath: 'email', options: { unique: false } } ] }, { store: 'animals', storeConfig: { keyPath: 'id', autoIncrement: true }, storeSchema: [ { name: 'name', keypath: 'name', options: { unique: true } } ] }], migrationFactory }; // For NgModule-based applications @NgModule({ imports: [ NgxIndexedDBModule.forRoot(dbConfig) ] }) export class AppModule { } // For Standalone API (main.ts or component providers) const appConfig: ApplicationConfig = { providers: [ provideIndexedDb(dbConfig) ] };

Debug

Known issues

breakingMajor version upgrades often coincide with Angular's ecosystem, requiring updates to maintain compatibility. Always check peer dependency ranges and release notes when upgrading Angular.

fix

Consult the `ngx-indexed-db` changelog and your Angular version's documentation for compatible package versions. Update `ngx-indexed-db` accordingly.

affects: >=8.0.0

gotchaPrior to version 19.2.0, `ngx-indexed-db` did not fully support Server-Side Rendering (SSR) and could lead to errors related to `window.indexedDB` being undefined. SSR is fully supported from v19.2.0 onwards.

fix

Upgrade to `ngx-indexed-db@19.2.0` or higher for robust SSR support. If using an older version, ensure IndexedDB operations are guarded by `isPlatformBrowser` or provide a custom `SERVER_INDEXED_DB` token.

affects: <19.2.0

gotchaDatabase schema changes (e.g., adding new object stores or indexes) require incrementing the `DBConfig.version` and providing a `migrationFactory`. Failing to do so will result in `DOMException` errors when opening the database.

fix

Always increment your `DBConfig.version` when modifying the schema. Implement corresponding migration functions in the `migrationFactory` to handle schema updates for existing databases.

affects: >=1.0.0

gotchaIndexedDB operations are asynchronous and transaction-based. Mismanaging transactions or attempting operations outside an active transaction will lead to errors.

fix

Ensure all read/write operations are performed within an active transaction. `ngx-indexed-db`'s observable API generally handles this, but be mindful when directly interacting with the underlying IDB objects if custom logic is involved.

affects: >=1.0.0

Errors

Common errors & fixes

Error: No `indexedDB` object found in `window`.

This typically occurs when running an Angular application with SSR without proper `ngx-indexed-db` configuration for the server environment, or when using an older version that lacked full SSR support.

fix

Upgrade to `ngx-indexed-db@19.2.0` or newer. Ensure your SSR setup correctly uses `platform-server` and `ngx-indexed-db` is configured, potentially providing a custom `SERVER_INDEXED_DB` token if needed.

DOMException: The database is not compatible with the version provided.

The `version` specified in `DBConfig` is lower than the version of the database already existing in the user's browser, or a version was incremented without providing the necessary migration functions.

fix

Always increment the `DBConfig.version` when making schema changes. Ensure that a corresponding migration function exists in `migrationFactory` for each version increment that needs to apply schema changes or data transformations.

DOMException: TransactionInactiveError: A request was placed against an IDBObjectStore, but the transaction which was used to retrieve it has since become inactive or finished.

An attempt was made to use an `IDBObjectStore` or `IDBIndex` object after the transaction it belongs to has completed, committed, or aborted. This usually means trying to perform an operation outside the scope of an active transaction.

fix

Ensure all database operations are completed within the lifetime of a single IndexedDB transaction. `ngx-indexed-db`'s service methods manage transactions, so avoid holding references to `objectStore` or `index` objects from a finished transaction.

NG0304: 'NgxIndexedDBModule' is not an NgModule

This error can occur if `NgxIndexedDBModule` is imported incorrectly, or if there's a version mismatch between `@angular/core` and `ngx-indexed-db` that causes compilation issues.

fix

Verify that `@angular/core` and `ngx-indexed-db` versions are compatible. Ensure `NgxIndexedDBModule.forRoot(dbConfig)` is placed correctly in the `imports` array of an NgModule, or use `provideIndexedDb(dbConfig)` in your providers if using standalone components/bootstrap.

Upgrade

Version history

22.0.0latest on npm

Audit

Dependencies

@angular/commonrequiredRequired for Angular core functionalities and dependency injection.

@angular/corerequiredCore Angular functionalities, including decorators, lifecycle hooks, and service provision.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/assuncaocharles/ngx-indexed-db ↗

packagehttps://www.npmjs.com/package/ngx-indexed-db ↗