{"id":16281,"library":"y-indexeddb","title":"Yjs IndexedDB Persistence","description":"y-indexeddb is a database adapter for Yjs, providing robust persistence for Yjs documents directly within the browser's IndexedDB. It enables critical features such as offline editing and significantly reduces the amount of data exchanged between a server and client by storing the full document state locally. The package is actively maintained, with the current stable version being 9.0.12, and receives frequent patch and minor updates. Its primary differentiation lies in its tight integration with the Yjs ecosystem, offering reliable CRDT-based persistence for collaborative applications without requiring a separate server-side database, making it ideal for browser-based, offline-first applications leveraging Yjs.","status":"active","version":"9.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/yjs/y-indexeddb","tags":["javascript","Yjs","CRDT","offline","shared editing","collaboration","concurrency","typescript"],"install":[{"cmd":"npm install y-indexeddb","lang":"bash","label":"npm"},{"cmd":"yarn add y-indexeddb","lang":"bash","label":"yarn"},{"cmd":"pnpm add y-indexeddb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for Yjs document synchronization and persistence.","package":"yjs","optional":false}],"imports":[{"note":"The package added an 'exports' field in v9.0.12, strongly favoring ESM imports. CommonJS 'require' may work but is not the recommended or future-proof approach, and might break in certain environments.","wrong":"const IndexeddbPersistence = require('y-indexeddb').IndexeddbPersistence;","symbol":"IndexeddbPersistence","correct":"import { IndexeddbPersistence } from 'y-indexeddb';"},{"note":"The package ships with TypeScript types, enabling strong typing for better development experience.","symbol":"IndexeddbPersistence (TypeScript Type)","correct":"import type { IndexeddbPersistence } from 'y-indexeddb';"}],"quickstart":{"code":"import * as Y from 'yjs';\nimport { IndexeddbPersistence } from 'y-indexeddb';\n\nconst ydoc = new Y.Doc();\nconst docName = 'my-shared-document';\n\n// Create a provider for IndexedDB persistence\nconst provider = new IndexeddbPersistence(docName, ydoc);\n\nprovider.on('synced', async () => {\n  console.log('Content from the database is loaded.');\n  // After content is loaded, you can safely interact with ydoc\n  if (ydoc.getText('myText').length === 0) {\n    ydoc.getText('myText').insert(0, 'Hello Yjs and IndexedDB!');\n    console.log('Initial text set:', ydoc.getText('myText').toString());\n  } else {\n    console.log('Loaded text:', ydoc.getText('myText').toString());\n  }\n\n  // Example of storing custom metadata\n  await provider.set('lastEdited', Date.now());\n  console.log('Metadata stored:', await provider.get('lastEdited'));\n});\n\n// Clean up resources when the document is no longer needed\n// Note: provider.destroy() is often automatically called if ydoc.destroy() is used.\n// For demonstration, manually destroying after a delay:\n// setTimeout(() => {\n//   provider.destroy();\n//   console.log('IndexedDB persistence destroyed.');\n// }, 5000);","lang":"typescript","description":"Demonstrates initializing a Yjs document with IndexedDB persistence and handling the 'synced' event to confirm data loading or initial content creation, including storing custom metadata."},"warnings":[{"fix":"Ensure all calls to `provider.clearData()` are `await`ed or handle the returned Promise explicitly (e.g., `provider.clearData().then(...)`).","message":"The `clearData()` method now returns a Promise. Calls to `clearData()` must be awaited to ensure the operation completes and to catch potential errors.","severity":"breaking","affected_versions":">=9.0.6"},{"fix":"Migrate to ESM `import` statements (e.g., `import { IndexeddbPersistence } from 'y-indexeddb';`). If using CommonJS, ensure your build setup correctly handles the `exports` map, or consider upgrading Node.js/bundler versions.","message":"The package introduced an `exports` field in `package.json` in v9.0.12. This change primarily affects how module resolvers (especially older ones or specific CommonJS setups) locate the package's entry points. While designed to improve ESM compatibility, it might lead to import resolution issues for projects still heavily relying on `require()` in environments not fully compliant with modern module resolution.","severity":"breaking","affected_versions":">=9.0.12"},{"fix":"Rely on the automatic destruction mechanism when destroying the Yjs document. Only manually call `provider.destroy()` if you need to specifically terminate the IndexedDB connection before the Yjs document itself is destroyed, or if managing multiple persistence providers for a single document.","message":"The `IndexeddbPersistence` provider automatically calls its `destroy()` method when its associated Yjs document (`ydoc`) is destroyed (e.g., via `ydoc.destroy()`). Manually calling `provider.destroy()` immediately after or before `ydoc.destroy()` can be redundant or lead to unexpected behavior if lifecycle hooks are involved.","severity":"gotcha","affected_versions":">=9.0.6"},{"fix":"Check the `package.json` for `y-indexeddb`'s peer dependency range (e.g., `\"yjs\": \"^13.0.0\"`) and install a compatible version of `yjs`.","message":"The package has a peer dependency on `yjs`. Ensure that the installed `yjs` version is compatible with `y-indexeddb` to avoid runtime errors or unexpected synchronization issues.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use ESM import syntax: `import { IndexeddbPersistence } from 'y-indexeddb';`. Ensure your environment supports ESM or use a bundler that transpiles it correctly. If using TypeScript, check `tsconfig.json` for `moduleResolution` settings.","cause":"Incorrect module import syntax, typically trying to use CommonJS `require()` with a package that primarily exposes ESM, or an incorrect named import.","error":"TypeError: IndexeddbPersistence is not a constructor"},{"fix":"Always `await` calls to `provider.clearData()` within an `async` function, or handle the Promise using `.then().catch()`.","cause":"The `clearData()` method, since v9.0.6, returns a Promise, but it is not being awaited or explicitly handled.","error":"Unhandled Promise Rejection Warning: Promise { <pending> } (or similar unhandled promise error) when calling clearData()"}],"ecosystem":"npm"}