API Reference - @liveblocks/node-prosemirror

@liveblocks/node-prosemirror provides a Node.js package to export and modify ProseMirror. Because Tiptap uses ProseMirror under the hood, this package can be used to modify Tiptap documents as well.

withProsemirrorDocument

withProsemirrorDocument is the main entry point to modifying a document on the server. It takes a room ID and a Liveblocks Node client, and returns a callback used to work with ProseMirror documents stored in Liveblocks.

import { Liveblocks } from "@liveblocks/node";import { withProsemirrorDocument } from "@liveblocks/node-prosemirror";
const liveblocks = new Liveblocks({  secret: "",});
await withProsemirrorDocument(  { roomId: "your-room-id", client: liveblocks },  (api) => {    // Modify your document with the api    // ...  });

Returns

returnsT
Returns the value you return from the api callback.

Options

roomIdstringRequired
The ID of the room to use.
clientLiveblocksRequired
The Liveblocks client to use.
schemaSchema
Optional. The ProseMirror schema to use for the document. If no schema is provided, the default schema is Tiptap StarterKit, Liveblocks mentions, and Liveblocks comments.
fieldstring
Optional. The field to use for the document. Defaults to default.

Returning data

Get your editor’s text content by returning api.getText() inside the callback.

const textContent = await withProsemirrorDocument(  { roomId: "my-room-id", client: liveblocks },  (api) => api.getText());
// "My content"console.log(textContent);

ProseMirror document API

You can easily modify your document with the ProseMirror document API.

api.update

Liveblocks provides api.update which is a callback that provides the current document and a ProseMirror transaction. This makes it easy to use ProseMirror’s built in functions. When you've finished, return the transaction and any changes will be persisted, and appear in realtime to connected users as soon as the update promise resolves.

await withProsemirrorDocument(  {    client,    roomId: "test-room",  },  async (api) => {    await api.update((doc, tr) => {      return tr.insertText("Hello world");    });  });

Returns

Nothing

Arguments

callback(doc: Node, tr: Transaction) => Transaction
doc is the ProseMirror document. tr is an editor state transaction. Transaction is a subclass of ProseMirror’s Transforms. On the ProseMirror website you can find a full list of transforms and transactions functions.

api.getText

Returns the text content of the document.: This api uses Tiptap’s getText internally. TextSerializers are a concept from Tiptap. If you are having trouble with a ProseMirror document, you may want to use api.getEditorState().doc.textBetween() instead.

const textContent = await withProsemirrorDocument(  { roomId: "my-room-id", client: liveblocks },  async (api) => {    return api.getText({      // Options      // ...    });  });

Returns

contentstring
Returns the text retrieved from the document.

Arguments

options.blockSeparatorstring
Optional. The separator to use for blocks, e.g. <br /> . Defaults to \n\n.
options.textSerializersstring
Optional. The serializers to use for text. Defaults to {}.

api.setContent

For convenience, some methods such as setContent are provided at the API level. Here’s an example that sets a document and returns the JSON content after it has been updated.

const exampleDoc = {  type: "doc",  content: [    {      type: "paragraph",      content: [        {          type: "text",          text: "Example Text",        },      ],    },  ],};
const json = await withProsemirrorDocument<string>(  {    client,    roomId: "test-room",  },  async (api) => {    await api.setContent(exampleDoc);    return JSON.stringify(api.toJSON());  });

Returns

Nothing

Arguments

contentnull | object | stringRequired
The content to replace your document.

doc.getEditorState

Returns the current ProseMirror state.

const editorState = await withProsemirrorDocument(  { roomId: "my-room-id", client: liveblocks },  async (api) => {    return api.getEditorState();  });

Returns

editorStateEditorState
Your editor’s ProseMirror state.

Arguments

None

api.toJSON

Returns a serialized JSON object representation of your document. See ProseMirror’s .toJSON documentation for more information.

const docAsJSON = await withProsemirrorDocument(  { roomId: "my-room-id", client: liveblocks },  async (api) => {    return api.toJSON();  });

Returns

editorStatestring
Your editor’s serialized JSON state.

Arguments

None

api.clearContent

Clears the content of the document.

await withProsemirrorDocument(  { roomId: "my-room-id", client: liveblocks },  async (api) => {    return api.clearContent();  });

Returns

Nothing

Arguments

None

api.toMarkdown

Returns a markdown string of your document.

const markdown = await withProsemirrorDocument(  { roomId: "my-room-id", client: liveblocks },  async (api) => {    return api.toMarkdown();  });

Returns

markdownstring
Returns the markdown string.

Arguments

serializerMarkdownSerializer
Optional. A markdown serializer to use. By default it uses the defaultMarkdownSerializer from prosemirror-markdown.

Custom markdown serializer

You can use a custom markdown serializer.

import { defaultMarkdownSerializer } from "prosemirror-markdown";
const mySerializer = new MarkdownSerializer({  marks: {    ...defaultMarkdownSerializer.marks,    em: {      open: "*",      close: "*",      mixable: true,      expelEnclosingWhitespace: true,    },  },});
const markdown = await withProsemirrorDocument(  { roomId: "my-room-id", client: liveblocks },  async (api) => {    return api.toMarkdown(mySerializer);  });