Today, we're excited to announce Yjs subdocuments support on Liveblocks, two months after introducing Liveblocks Yjs. This new feature brings a more dynamic and efficient way to manage collaborative editing and data handling of Yjs documents.
Join thousands of companies using Liveblocks to build multiplayer experiences for people and agents.
Today, we’re excited to announce Yjs subdocuments support on Liveblocks, two months after introducing Liveblocks Yjs. This new feature brings a more dynamic and efficient way to manage collaborative editing and data handling of Yjs documents.
Start using subdocuments now by updating each Liveblocks package in your project
to the @latest version.
If you use any other Liveblocks packages, make sure to include those too.
The integration of Yjs subdocuments into Liveblocks is designed to be as seamless as possible. Subdocuments introduce a way to lazy-load parts of your document, making data management more scalable and performant when working with large documents.
Typically, you’d store different subdocuments within a Y.Map in the root
document. This approach helps in keeping document structure both organized and
accessible. Accessing these subdocuments is straightforward via the
doc.getSubdocs() function, which returns a Set<Y.Doc> of all subdocuments,
even if they’re deeply nested in your data structure. Subdocuments added to your
document will automatically sync with the Liveblocks back end, no additional
coding is required.
One of the key advantages of subdocuments is that they don’t contain any content
upon initial load. This lightweight approach speeds up the loading process and
saves resources. When you need to access the content of a subdocument, simply
call subdoc.load() or the utility method provider.loadSubdoc(guid). This
action prompts the Liveblocks server to load and fetch the document. When it’s
complete, a
synced event
will fire.
To keep track of subdocuments within your document, users can utilize the
doc.on("subdocs", {added, removed, loaded}, () => {}) listener. This
functionality is particularly useful for scenarios where you need to load newly
added documents or manage dynamic content changes within your collaborative
session.
With Yjs subdocuments, we’re also introducing the capability to manipulate
subdocuments programmatically using the Liveblocks REST API. The API accepts the
?guid= parameter, allowing for direct operations on subdocuments. This is
particularly useful for creating AI agents that can act on your documents.
Here’s how you can fetch and update a subdoc using the REST API:
If you’d like to get started with Liveblocks Yjs and subdocuments, make sure to read our guides.
Remember to upgrade your packages to start using subdocuments!
