y-indexeddb

library9.0.12jsnpmunverified

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.

database

npm install y-indexeddb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · Y-INDEXEDDB

y-indexeddb

databasejavascriptv9.0.12

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.

IndexeddbPersistence

✓ import { IndexeddbPersistence } from 'y-indexeddb';

✗ const IndexeddbPersistence = require('y-indexeddb').IndexeddbPersistence;

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.

IndexeddbPersistence (TypeScript Type)

✓ import type { IndexeddbPersistence } from 'y-indexeddb';

The package ships with TypeScript types, enabling strong typing for better development experience.

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.

import * as Y from 'yjs'; import { IndexeddbPersistence } from 'y-indexeddb'; const ydoc = new Y.Doc(); const docName = 'my-shared-document'; // Create a provider for IndexedDB persistence const provider = new IndexeddbPersistence(docName, ydoc); provider.on('synced', async () => { console.log('Content from the database is loaded.'); // After content is loaded, you can safely interact with ydoc if (ydoc.getText('myText').length === 0) { ydoc.getText('myText').insert(0, 'Hello Yjs and IndexedDB!'); console.log('Initial text set:', ydoc.getText('myText').toString()); } else { console.log('Loaded text:', ydoc.getText('myText').toString()); } // Example of storing custom metadata await provider.set('lastEdited', Date.now()); console.log('Metadata stored:', await provider.get('lastEdited')); }); // Clean up resources when the document is no longer needed // Note: provider.destroy() is often automatically called if ydoc.destroy() is used. // For demonstration, manually destroying after a delay: // setTimeout(() => { // provider.destroy(); // console.log('IndexedDB persistence destroyed.'); // }, 5000);

Debug

Known issues

breakingThe `clearData()` method now returns a Promise. Calls to `clearData()` must be awaited to ensure the operation completes and to catch potential errors.

fix

Ensure all calls to `provider.clearData()` are `await`ed or handle the returned Promise explicitly (e.g., `provider.clearData().then(...)`).

affects: >=9.0.6

breakingThe 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.

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.

affects: >=9.0.12

gotchaThe `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.

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.

affects: >=9.0.6

gotchaThe 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.

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`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: IndexeddbPersistence is not a constructor

Incorrect module import syntax, typically trying to use CommonJS `require()` with a package that primarily exposes ESM, or an incorrect named import.

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.

Unhandled Promise Rejection Warning: Promise { <pending> } (or similar unhandled promise error) when calling clearData()

The `clearData()` method, since v9.0.6, returns a Promise, but it is not being awaited or explicitly handled.

fix

Always `await` calls to `provider.clearData()` within an `async` function, or handle the Promise using `.then().catch()`.

Upgrade

Version history

9.0.12latest on npm

Audit

Dependencies

yjsrequiredPeer dependency required for Yjs document synchronization and persistence.

Agent activity

25 hits · last 30 days

node