Upgrade a local document to collaboration

Use upgradeToCollaboration() when a single local DOCX is already open and the person decides to make that live Editor collaborative. The operation creates a new room from the current document and comments, then attaches the Editor to it in place.

Create the room

Wait until the local Editor is ready, then pass a supported collaboration target in create mode. This snippet uses the preview configuration API:

Here, superdoc is your existing Editor and session.collaborationToken comes from your application's authenticated session. Replace the example server address with your configured provider. The token must be authorized to create contract-123; this snippet does not provide a server or sign-in flow.

const { roomId, documentId } = await superdoc.upgradeToCollaboration({
  collaboration: {
    providerType: 'hocuspocus',
    documentId: 'contract-123',
    serverUrl: 'wss://collaboration.example.com',
    token: session.collaborationToken,
    roomMode: 'create',
  },
});

The promise returns the attached roomId and local documentId when the collaborative runtime is ready. The same Editor instance stays mounted, so application controls and lifecycle ownership remain in place. Concurrent requests for the same target await the same outcome; a different target fails with code: 'collaboration-upgrade-target-conflict' without changing the pending upgrade.

The operation supports one DOCX and a new v2 room. It does not join an existing room or merge the local document with remote content. If the target already exists, the rejected promise carries code: 'collaboration-v2-room-already-exists'; stop and let the application choose a different room or reopen the document with roomMode: 'join'. The local document remains available after rejection.

Migrate existing collaboration data separately

Moving a final v1 recovery bundle into a v2 room is a server-side migration, not a live browser upgrade. The Node-only superdoc/collaboration-upgrade-engine subpath builds and validates provider-free upgrade artifacts without connecting to a room. It requires Node.js 20 or newer and should be paired with provider-specific read, write, and fresh-client validation.

Start with Migrate from v1 before planning that operation. For ordinary browser connections, use Connect two editors.