YJS Utilities
The @blocknote/core/yjs export provides utilities for converting between BlockNote blocks and YJS collaborative documents. These utilities are useful when you need to work with YJS documents outside of the standard collaboration setup, such as importing existing content or working with YJS documents programmatically.
Important: This package is for advanced use cases where you need to convert between BlockNote blocks and YJS documents programmatically. For most use cases, you should use the collaboration features directly instead.
Import
import {
blocksToYDoc,
blocksToYXmlFragment,
yDocToBlocks,
yXmlFragmentToBlocks,
} from "@blocknote/core/yjs";Overview
YJS utilities enable bidirectional conversion between:
- BlockNote blocks ↔ Y.Doc (YJS document)
- BlockNote blocks ↔ Y.XmlFragment (YJS XML fragment)
These conversions are essential for:
- Importing existing BlockNote content into a YJS document for collaboration
- Exporting content from a YJS document back to BlockNote blocks
- Working with YJS documents programmatically without an active editor instance
Converting Blocks to YJS Documents
blocksToYDoc
Converts BlockNote blocks into a Y.Doc. This is useful when importing existing content to a Y.Doc for the first time.
Important: This should not be used to rehydrate a Y.Doc from a database once collaboration has begun, as all history will be lost.
function blocksToYDoc<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
blocks: PartialBlock<BSchema, ISchema, SSchema>[],
xmlFragment?: string,
): Y.Doc;Parameters:
editor- The BlockNote editor instanceblocks- Array of blocks to convertxmlFragment- Optional XML fragment name (defaults to"prosemirror")
Returns: A new Y.Doc containing the converted blocks
Example:
import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYDoc } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const blocks = [
{
type: "paragraph",
content: "Hello, world!",
},
{
type: "heading",
props: { level: 1 },
content: "My Document",
},
];
// Convert blocks to Y.Doc
const ydoc = blocksToYDoc(editor, blocks);
// Now you can use this Y.Doc with a YJS provider for collaboration
const provider = new WebrtcProvider("my-room", ydoc);blocksToYXmlFragment
Converts BlockNote blocks into a Y.XmlFragment. This is useful when you want to work with a specific XML fragment within a Y.Doc.
function blocksToYXmlFragment<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
blocks: Block<BSchema, ISchema, SSchema>[],
xmlFragment?: Y.XmlFragment,
): Y.XmlFragment;Parameters:
editor- The BlockNote editor instanceblocks- Array of blocks to convertxmlFragment- Optional existing Y.XmlFragment to populate (creates new one if not provided)
Returns: A Y.XmlFragment containing the converted blocks
Example:
import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYXmlFragment } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const doc = new Y.Doc();
const fragment = doc.getXmlFragment("my-fragment");
const blocks = [
{
type: "paragraph",
content: "Content for fragment",
},
];
// Convert blocks to the XML fragment
blocksToYXmlFragment(editor, blocks, fragment);Converting YJS Documents to Blocks
yDocToBlocks
Converts a Y.Doc back into BlockNote blocks. This is useful for reading content from a YJS document.
function yDocToBlocks<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
ydoc: Y.Doc,
xmlFragment?: string,
): Block<BSchema, ISchema, SSchema>[];Parameters:
editor- The BlockNote editor instanceydoc- The Y.Doc to convertxmlFragment- Optional XML fragment name (defaults to"prosemirror")
Returns: Array of BlockNote blocks
Example:
import { BlockNoteEditor } from "@blocknote/core";
import { yDocToBlocks } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const ydoc = new Y.Doc();
// ... Y.Doc is populated through collaboration or other means ...
// Convert Y.Doc back to blocks
const blocks = yDocToBlocks(editor, ydoc);
console.log(blocks); // Array of BlockNote blocksyXmlFragmentToBlocks
Converts a Y.XmlFragment back into BlockNote blocks.
function yXmlFragmentToBlocks<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
xmlFragment: Y.XmlFragment,
): Block<BSchema, ISchema, SSchema>[];Parameters:
editor- The BlockNote editor instancexmlFragment- The Y.XmlFragment to convert
Returns: Array of BlockNote blocks
Example:
import { BlockNoteEditor } from "@blocknote/core";
import { yXmlFragmentToBlocks } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const doc = new Y.Doc();
const fragment = doc.getXmlFragment("my-fragment");
// ... Fragment is populated through collaboration or other means ...
// Convert fragment back to blocks
const blocks = yXmlFragmentToBlocks(editor, fragment);Round-trip Conversion
All conversion functions support round-trip conversion, meaning you can convert blocks → YJS → blocks and get back the same content:
import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYDoc, yDocToBlocks } from "@blocknote/core/yjs";
const editor = BlockNoteEditor.create();
const originalBlocks = [
{
type: "paragraph",
content: "Test content",
},
];
// Convert to Y.Doc and back
const ydoc = blocksToYDoc(editor, originalBlocks);
const convertedBlocks = yDocToBlocks(editor, ydoc);
// originalBlocks and convertedBlocks are equivalent
console.log(originalBlocks); // Same structure as convertedBlocksRelated Documentation
- Real-time Collaboration - Learn how to set up collaboration in BlockNote
- Manipulating Content - Working with blocks and inline content
- Server Processing - Server-side processing for BlockNote (uses these YJS utilities internally)