Initialize a shared document

Your application has a DOCX that Alex and Sam need to edit together. Choose one place to create its shared room. After that, everyone—including the creator—joins the existing room.

Start with the local two-editor example. Keep its Hocuspocus server running throughout this walkthrough; it stores rooms only in memory.

Create once, then join

First open	Another person arrives	Return to the document
Alex creates a room from the DOCX.	Sam joins the room and receives its content.	Alex joins the same room, including its edits.
`roomMode: 'create'`	`roomMode: 'join'`	`roomMode: 'join'`

create is not “open or create.” It fails if the room already exists. join does not initialize a missing room from the supplied file.

If several backend workers or browsers could create the same room, follow coordinate room creation before enabling them. The SDK cannot reserve a room on your collaboration server.

Recover an interrupted initialization

A create attempt can stop after writing only part of a room. A later join may report that initialization is still in progress or has stalled. Do not treat that result as permission for several browsers or workers to retry create together. SuperDoc can refuse a partial room without writing to it, but the collaboration provider does not give SuperDoc an exclusive, server-authorized initializer.

If your application retries automatically, reserve one initializer per document and source revision in your backend. Give it a server-verified room and attempt number. Your collaboration server must admit initialization writes only from that attempt, including writes sent during the connection's initial synchronization. Before assigning a replacement attempt, stop or reject writes from the previous attempt, including connections that were already open, and drain any writes already in flight. Expiring a timer or checking a credential only when a connection opens is not enough. Keep other editors out until the room is ready.

Retry the existing room only if SuperDoc accepts it as resumable. If it cannot be resumed, leave the partial room intact. For a room that was never published to editors, your application may use its retained source DOCX to initialize a new room ID. Point editors at the new room only after a fresh peer can join and your server confirms that the room state has been stored. If the old room may contain edits, or its stored state is uncertain, recover from authoritative room storage instead; never silently replace those edits with an older DOCX.

This is application and provider coordination, not a built-in cross-provider recovery guarantee. See the server initialization checklist before enabling automatic retries. collaboration-ready confirms fresh-peer visibility for built-in browser providers, not durable storage; provider extensions retain their existing local-readiness behavior.

1. Create the room from a DOCX

In the example, open http://localhost:5173/?mode=create&user=Alex. Alex's editor imports the sample DOCX into a new room and shows Connected. when it is ready.

For a browser create open with a built-in provider, collaboration-ready waits until an independent provider connection can receive the complete seed and validate the room. If that does not happen within syncTimeoutMs (30 seconds by default), the open reports an error instead of readiness. This confirms shared-room visibility for a fresh peer, not durable storage on your server. Keep the creator connected until your server has retained the room for later joins. Provider extensions retain their existing local-readiness behavior on create; do not use their collaboration-ready callback as a shared-room handoff signal.

With the preview configuration API, put the connection in the document's collaboration field. These are the creator's settings:

import type { DocumentCollaborationConfig } from 'superdoc';

const createConnection = {
  providerType: 'hocuspocus',
  serverUrl: 'ws://127.0.0.1:1234',
  documentId: 'example-room',
  roomMode: 'create',
} satisfies DocumentCollaborationConfig;

In your application's document configuration, use collaboration: createConnection for this first open. Leave the pinned example unchanged; its URL selects the same room operation.

In your application, assign a stable room ID to each shared document. Store that association so future editors can find the same room. Do not generate a new ID on every page load or reuse one room for unrelated documents.

The application chooses who initializes the room. Do not make every visitor try to create it. The collaboration server must still authorize access; knowing a room ID does not grant permission.

2. Join the existing room

After Alex's tab shows Connected., open http://localhost:5173/?user=Sam. The server address and room ID stay the same; only the operation changes:

const joinConnection = {
  ...createConnection,
  roomMode: 'join',
} satisfies DocumentCollaborationConfig;

Use collaboration: joinConnection for later opens. The example still supplies the sample DOCX, but the joiner receives the room's shared content. Supplying the original file does not reset the room.

Type a short sentence in Sam's editor and confirm that Alex sees it.

3. Reopen without resetting

Keep Alex connected while you close Sam's tab and reopen http://localhost:5173/?user=Sam. His sentence should still be there. With Sam connected again, Alex can close his tab and return using http://localhost:5173/?user=Alex.

Do not reuse Alex's original mode=create address to reopen the document. The person who created the room is now a joiner too.

If creation reports that the room exists, reopen the intended document with join; do not overwrite it. If joining fails, check the connection, room ID, access, and whether initialization completed. A failed join is not permission to create a replacement from an older file.

Choose where initialization belongs

The browser path above works when the first editor supplies the DOCX. Two other starting points have different owners:

Your application starts with…	Initialize through…
A DOCX opened for its first shared editing session	The browser editor, as above.
A local editor with unsaved changes that someone wants to share	`upgradeToCollaboration()`, which creates a new room from the current document.
A backend workflow that prepares the document before anyone opens it	The Node.js SDK, opening the DOCX with a collaboration target and explicit `roomMode: 'create'`. Browsers then join that room.

The Hocuspocus server transports shared state; it does not import a DOCX by itself. Server-side initialization still needs a SuperDoc client to read the file and create the document in the room. Choose one initialization path, not competing browser and backend creators.

Keep the room after a restart

Reopening this example proves that a new editor receives the existing room's edits. It does not prove durable saving. This server has no storage integration: restarting it clears its rooms, and a room can also be unloaded after its last editor leaves. Keep at least one editor connected during the walkthrough.

onCollaborationReady is not a storage acknowledgment. To reopen after everyone leaves or the server restarts, your server needs persistent room storage.

Next, save and restore a room so the document survives everyone leaving and the server restarting.