Skip to main content
Use this guide when you are combining:
  • The SuperDoc SDK (@superdoc-dev/sdk or superdoc-sdk) for headless/document automation
  • SuperDoc real-time collaboration (Yjs providers like Liveblocks, Hocuspocus, or SuperDoc Yjs)

​
Two session types

These are different concepts:
  • Collaboration session: a shared Yjs room/document (ydoc + provider) used by browser editors.
  • SDK session: a SuperDoc Document Engine editing session created by doc.open.
The SDK does not directly attach to a provider object. It operates through Document Engine sessions.

​
SuperDoc JS collaboration contract

In the browser, SuperDoc uses a provider-agnostic contract: 
import * as Y from "yjs";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import { SuperDoc } from "superdoc";

const ydoc = new Y.Doc();
const provider = new LiveblocksYjsProvider(room, ydoc);

new SuperDoc({
  selector: "#editor",
  modules: {
    collaboration: { ydoc, provider },
  },
});
See Collaboration Configuration for details.

​
Using SDK sessions with collaboration-enabled documents

The SDK can work against a document that is also edited collaboratively, but interaction is through SDK/CLI session APIs. 
import { createSuperDocClient } from "@superdoc-dev/sdk";

const client = createSuperDocClient();
await client.connect();

await client.doc.open({ doc: "./contract.docx" });

const sessions = await client.doc.session.list();
console.log(sessions);
You can target a specific active SDK session: 
await client.doc.session.setDefault({ id: "session-id" });
await client.doc.info();

​
Provider choice is unchanged

Provider setup still happens in your app using SuperDoc JS: The SDK integration pattern does not change by provider.

​
Practical guidance

  • Use collaboration providers for multi-user real-time editing UX.
  • Use SDK sessions for backend automation, workflows, and deterministic operations.
  • Keep the distinction explicit in your architecture: provider state vs SDK/CLI session state.