{"id":16456,"library":"ngx-indexed-db","title":"Angular IndexedDB Wrapper","description":"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.","status":"active","version":"22.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/assuncaocharles/ngx-indexed-db","tags":["javascript","indexed","db","indexeddb","angular","ng","ngx","storage","schema","typescript"],"install":[{"cmd":"npm install ngx-indexed-db","lang":"bash","label":"npm"},{"cmd":"yarn add ngx-indexed-db","lang":"bash","label":"yarn"},{"cmd":"pnpm add ngx-indexed-db","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Angular core functionalities and dependency injection.","package":"@angular/common","optional":false},{"reason":"Core Angular functionalities, including decorators, lifecycle hooks, and service provision.","package":"@angular/core","optional":false}],"imports":[{"note":"Used for module-based Angular applications (e.g., in an NgModule's imports array).","wrong":"const NgxIndexedDBModule = require('ngx-indexed-db')","symbol":"NgxIndexedDBModule","correct":"import { NgxIndexedDBModule } from 'ngx-indexed-db'"},{"note":"The interface for configuring your IndexedDB database schema and version.","wrong":"import type { DBConfig } from 'ngx-indexed-db'","symbol":"DBConfig","correct":"import { DBConfig } from 'ngx-indexed-db'"},{"note":"Recommended for standalone Angular applications or when using the providers array in an NgModule.","symbol":"provideIndexedDb","correct":"import { provideIndexedDb } from 'ngx-indexed-db'"},{"note":"The primary service injected into components/services to interact with the IndexedDB.","symbol":"NgxIndexedDBService","correct":"import { NgxIndexedDBService } from 'ngx-indexed-db'"},{"note":"An InjectionToken used to provide a custom IndexedDB implementation, primarily for SSR or testing environments.","symbol":"SERVER_INDEXED_DB","correct":"import { SERVER_INDEXED_DB } from 'ngx-indexed-db'"}],"quickstart":{"code":"import { NgModule, ApplicationConfig } from '@angular/core';\nimport { NgxIndexedDBModule, provideIndexedDb, DBConfig } from 'ngx-indexed-db';\n\n// Ahead of time compiles requires an exported function for factories\nexport function migrationFactory() {\n  return {\n    1: (db, transaction) => {\n      const store = transaction.objectStore('people');\n      store.createIndex('country', 'country', { unique: false });\n    },\n    3: (db, transaction) => {\n      const store = transaction.objectStore('people');\n      store.createIndex('age', 'age', { unique: false });\n    }\n  };\n}\n\nconst dbConfig: DBConfig  = {\n  name: 'MyDb',\n  version: 3,\n  objectStoresMeta: [{\n    store: 'people',\n    storeConfig: { keyPath: 'id', autoIncrement: true },\n    storeSchema: [\n      { name: 'name', keypath: 'name', options: { unique: false } },\n      { name: 'email', keypath: 'email', options: { unique: false } }\n    ]\n  }, {\n    store: 'animals',\n    storeConfig: { keyPath: 'id', autoIncrement: true },\n    storeSchema: [\n      { name: 'name', keypath: 'name', options: { unique: true } }\n    ]\n  }],\n  migrationFactory\n};\n\n// For NgModule-based applications\n@NgModule({\n  imports: [\n    NgxIndexedDBModule.forRoot(dbConfig)\n  ]\n})\nexport class AppModule { }\n\n// For Standalone API (main.ts or component providers)\nconst appConfig: ApplicationConfig = {\n  providers: [\n    provideIndexedDb(dbConfig)\n  ]\n};","lang":"typescript","description":"This quickstart demonstrates configuring ngx-indexed-db for both NgModule and standalone Angular applications, including defining the database schema and implementing version migrations."},"warnings":[{"fix":"Consult the `ngx-indexed-db` changelog and your Angular version's documentation for compatible package versions. Update `ngx-indexed-db` accordingly.","message":"Major version upgrades often coincide with Angular's ecosystem, requiring updates to maintain compatibility. Always check peer dependency ranges and release notes when upgrading Angular.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<19.2.0"},{"fix":"Always increment your `DBConfig.version` when modifying the schema. Implement corresponding migration functions in the `migrationFactory` to handle schema updates for existing databases.","message":"Database 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"IndexedDB operations are asynchronous and transaction-based. Mismanaging transactions or attempting operations outside an active transaction will lead to errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: No `indexedDB` object found in `window`."},{"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.","cause":"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.","error":"DOMException: The database is not compatible with the version provided."},{"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.","cause":"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.","error":"DOMException: TransactionInactiveError: A request was placed against an IDBObjectStore, but the transaction which was used to retrieve it has since become inactive or finished."},{"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.","cause":"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.","error":"NG0304: 'NgxIndexedDBModule' is not an NgModule"}],"ecosystem":"npm"}