Why you can’t delete Yjs documents

When working with Yjs and Liveblocks, you might wonder why there’s no way to delete a Yjs document without deleting the entire room. This isn’t a limitation—it’s a fundamental aspect of how Yjs works as a Conflict-free Replicated Data Type (CRDT). Understanding this behavior is essential for building robust collaborative applications.

Yjs stores changes, not state

Unlike traditional databases that store the current state of your data, Yjs stores a complete history of changes made to a document. When you make an edit in a Yjs document, you’re not replacing the old data—you’re appending a new change to the document’s history.

This approach is what enables Yjs to handle realtime collaboration so effectively. When multiple users edit the same document simultaneously, Yjs can merge their changes automatically without conflicts, even if they’re working offline.

The role of tombstones

When you "delete" content in a Yjs document, the data isn’t actually removed. Instead, Yjs creates a tombstone—a marker that indicates the content has been deleted. These tombstones are crucial for maintaining consistency across all users.

Tombstones serve several important purposes:

• Conflict resolution: If one user deletes content while another user is editing it offline, the tombstone helps Yjs resolve this conflict when they reconnect.
• Causal ordering: Tombstones maintain the causal relationship between operations, ensuring that edits are applied in the correct order.
• Synchronization: When a new user joins or an offline user reconnects, tombstones ensure they see the correct state of the document.

Without tombstones, Yjs wouldn’t be able to guarantee that all users see the same document state, especially in scenarios with offline editing or network issues.

Offline peers and history

One of Yjs’s most powerful features is its ability to handle offline editing. Users can continue working on a document even without an internet connection, and their changes will sync automatically when they reconnect.

For this to work, Yjs needs to maintain the complete history of changes. When an offline user reconnects, their client sends all the changes they made while offline. The server then merges these changes with any updates from other users, using the document’s history to resolve conflicts.

If you could delete parts of a document’s history, offline users wouldn’t be able to sync properly. Their changes might conflict with the "deleted" history, leading to data loss or inconsistent states across different users.

Why you can’t delete Yjs documents

Given how Yjs works, there’s no safe way to delete a Yjs document without potentially breaking synchronization for offline or slow-to-sync users. Here’s why:

1. Active sessions: Users might have the document open and be making changes. Deleting the document would cause their changes to fail or create a new document unintentionally.

2. Offline users: Someone might be editing the document offline. When they reconnect, they’d try to sync changes to a document that no longer exists.

3. Pending synchronization: Changes might still be in transit across the network. Deleting the document could cause these changes to be lost or create inconsistencies.

4. CRDT guarantees: Yjs’s conflict-free guarantees depend on having access to the complete history. Partial deletion would break these guarantees.

What you can do instead

While you can’t delete a Yjs document directly, you have several options:

Delete the entire room

The only way to fully delete a Yjs document is to delete the room that contains it. This ensures that all associated data is removed cleanly, and there’s no risk of orphaned changes or synchronization issues.

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxx…xxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
// Delete the room and all its data, including the Yjs documentawait liveblocks.deleteRoom("my-room-id");

You can then create a new room and start afresh.

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxx…xxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
// Create a new roomawait liveblocks.createRoom("my-new-room-id", {  defaultAccesses: ["room:write"],});

When deleting a room, bear in mind that all data associated with it is removed, including threads, Storage, and more.

Clear the document content

If you want to “reset” a document without deleting it, you can clear its Yjs content by replacing it with an empty string, keeping the room. However this doesn’t actually delete the document’s history—it adds a new “delete everything” operation, meaning the document data size has got larger instead of smaller.

import * as Y from "yjs";import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxx…xxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
// Get the current documentconst update = await liveblocks.getYjsDocumentAsBinaryUpdate("my-room-id");const yDoc = new Y.Doc();Y.applyUpdate(yDoc, new Uint8Array(update));
// Clear the content (example with Y.Text)const yText = yDoc.getText("content");yText.delete(0, yText.length);
// Send the update backconst yUpdate = Y.encodeStateAsUpdate(yDoc);await liveblocks.sendYjsBinaryUpdate("my-room-id", yUpdate);

Learn more

For more information about working with Yjs and Liveblocks, check out these guides:

• Yjs best practices and tips
• How to use your Y.Doc on the server
• Modifying Yjs document data with the REST API
• Data storage