{"id":17576,"library":"dexie-observable","title":"Dexie Observable Addon","description":"Dexie.Observable is an addon for Dexie.js that significantly enhances IndexedDB functionality by enabling cross-window and cross-instance database change observation. It introduces an event mechanism, similar to `localStorage`'s `onstorage`, specifically for IndexedDB, allowing web applications to react in real-time to data modifications, irrespective of the originating tab or worker. This ensures views remain synchronized and up-to-date across all connected clients. The package is an integral part of the Dexie.js ecosystem, fully compatible with Dexie v4.x, and typically releases in alignment with Dexie.js's maintenance and feature updates. Although the package version provided is `4.0.1-beta.13`, it functions within the broader stable Dexie v4 environment. Furthermore, it forms the foundational layer for `Dexie.Syncable.js`, which provides robust two-way data replication capabilities with remote servers.","status":"active","version":"4.0.1-beta.13","language":"javascript","source_language":"en","source_url":"https://github.com/dexie/Dexie.js","tags":["javascript","indexeddb","browser","dexie","addon","typescript"],"install":[{"cmd":"npm install dexie-observable","lang":"bash","label":"npm"},{"cmd":"yarn add dexie-observable","lang":"bash","label":"yarn"},{"cmd":"pnpm add dexie-observable","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core database library that dexie-observable extends.","package":"dexie","optional":false}],"imports":[{"note":"Dexie itself is typically a default import. `dexie-observable` is imported for its side-effects, extending the Dexie prototype, so there are no named exports to import directly from 'dexie-observable'.","wrong":"import { Dexie } from 'dexie';\nimport { DexieObservable } from 'dexie-observable';","symbol":"Dexie","correct":"import Dexie from 'dexie';\nimport 'dexie-observable';"},{"note":"The event name is 'changes' (plural), not 'change', and the callback receives an array of `DatabaseChange` objects.","wrong":"db.on('change', () => { /* ... */ });","symbol":"db.on('changes')","correct":"db.on('changes', (changes) => { /* handle changes */ });"},{"note":"Use the `$$` prefix for the primary key to automatically generate UUIDs when adding new objects. Without `$$`, 'uuid' would be a regular indexed property.","wrong":"db.version(1).stores({ friends: 'uuid,name' });","symbol":"$$uuid primary key","correct":"db.version(1).stores({ friends: '$$uuid,name' });"}],"quickstart":{"code":"import Dexie from 'dexie';\nimport 'dexie-observable'; // Enables db.on('changes')\n\nconst db = new Dexie('ObservableTestDB');\ndb.version(1).stores({\n  friends: '$$uuid,name,age'\n});\n\n// Subscribe to database changes across all windows/instances\ndb.on('changes', (changes) => {\n  console.log('Database changes detected:');\n  changes.forEach((change) => {\n    switch (change.type) {\n      case 1: // CREATED\n        console.log(`CREATED: ${JSON.stringify(change.obj)}`);\n        break;\n      case 2: // UPDATED\n        console.log(`UPDATED: Old: ${JSON.stringify(change.oldObj)}, New: ${JSON.stringify(change.obj)}`);\n        break;\n      case 3: // DELETED\n        console.log(`DELETED: ${JSON.stringify(change.oldObj)}`);\n        break;\n    }\n  });\n});\n\nasync function addFriend() {\n  await db.friends.add({ name: 'Alice', age: 30 });\n  console.log('Added Alice. Check other browser tabs!');\n  await db.friends.add({ name: 'Bob', age: 25 });\n  console.log('Added Bob. Check other browser tabs!');\n}\n\naddFriend();","lang":"typescript","description":"This example demonstrates how to initialize Dexie with the observable addon, define a store using UUID primary keys, and subscribe to the `db.on('changes')` event to react to database modifications, including those from other browser windows."},"warnings":[{"fix":"Add a new version to your database schema, even if it's an empty `db.version(X).stores({});` entry, after your existing schema. This triggers the necessary upgrade logic.","message":"When integrating `dexie-observable` with an existing Dexie database, a schema upgrade is mandatory to allow the addon to install its internal tables. Failing to do so will prevent `dexie-observable` from functioning correctly.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use `import 'dexie-observable';` after `import Dexie from 'dexie';`. Any functionality, like `db.on('changes')`, will then be available on your Dexie database instance.","message":"The `dexie-observable` package is primarily imported for its side-effects, meaning it extends the Dexie prototype directly. There are no named exports from 'dexie-observable' itself that you would typically import and use directly.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Monitor the Dexie.js GitHub releases for a stable `dexie-observable` v4.x release, or use with caution in production environments, ensuring thorough testing.","message":"The package version `4.0.1-beta.13` indicates it is a beta release. While generally stable for use with Dexie v4, users should be aware that it's not a final major release and could potentially introduce minor changes before a stable 4.x version of the addon is officially released.","severity":"gotcha","affected_versions":"4.0.1-beta.13"},{"fix":"To use a custom UUID generator, assign your function to `Dexie.createUUID = myCustomUUIDFunction;` before initializing your database. Ensure your custom function returns a unique string suitable for primary keys.","message":"The `$$` prefix for a primary key (e.g., `$$uuid`) is a special syntax introduced by `dexie-observable` to automatically generate UUID strings for that key. If you need a custom UUID generation logic, you can override `Dexie.createUUID`.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `import Dexie from 'dexie';` is followed by `import 'dexie-observable';` in your module. Also, make sure you are calling `db.on()` on an instance of Dexie created *after* the import.","cause":"`dexie-observable` has not been correctly imported and initialized, or the `db.on` method is being called before the addon has extended the Dexie prototype.","error":"TypeError: db.on is not a function"},{"fix":"If using an existing database, ensure you have added a new, empty version to your schema definition (`db.version(X).stores({});`) to trigger the addon's installation. Verify browser compatibility with cross-window IndexedDB events.","cause":"The required schema upgrade for `dexie-observable` to create its internal tables was not performed, or the browser's IndexedDB implementation is not firing the necessary events.","error":"Changes not propagating across browser windows/tabs."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}