Connect two editors

Connect Alex and Sam to the same document. Start with the working example, then look at the configuration that connects them.

Try it here

The editors connect automatically. Expand the demo, then change Monday to Friday in Alex's document. Watch Sam's document update. Alex's cursor is blue; Sam's is green. This sample is temporary; do not enter private information.

1. Start the example

Download or clone the collaboration example. It includes the browser app, a sample DOCX, and a local Hocuspocus server.

You need Node.js 22.12 or newer and pnpm 11. In the example's collaboration directory, run:

pnpm install --ignore-scripts
pnpm dev

The example pins SuperDoc 2.11.0 and Hocuspocus 2.15.3. The install command skips dependency lifecycle scripts. Keep the terminal running: it serves the app on port 5173 and the collaboration connection on port 1234.

2. Open Alex and Sam's editors

Open these addresses in separate tabs, in this order:

Wait for Alex's tab to show Connected. before opening Sam's. Then wait for Sam's tab to show the same status. Place the browser windows side by side so you can see both documents.

3. Edit together

In Alex's editor, change Monday to Friday. Watch the delivery date update in Sam's editor without reloading.

Now type a reply in Sam's editor. It appears in Alex's editor too. Both editors can send and receive changes; neither is a read-only preview of the other.

Configure your application

The connection belongs to the document. Both editors use the same server and room ID; the creator uses create, and everyone else uses join.

import { SuperDoc, type DocumentCollaborationConfig } from 'superdoc';
import 'superdoc/style.css';

const collaboration = {
  providerType: 'hocuspocus',
  documentId: 'example-room',
  serverUrl: 'ws://127.0.0.1:1234',
  roomMode: 'join',
  syncTimeoutMs: 45_000,
} satisfies DocumentCollaborationConfig;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: { url: '/sample.docx', collaboration },
  user: { name: 'Sam', email: '[email protected]' },
});

Provide an #editor element and serve your DOCX at /sample.docx. Use these settings when integrating the preview API into your application, not as a patch to the pinned example.

The mode and user URL parameters belong to this example, not SuperDoc. The app reads them to choose the room operation and display name.

Both editors supply the sample DOCX. The creator uses it to initialize the room. The joiner reads the room's shared content; supplying the file again does not overwrite it.

The example shows Connected. when onCollaborationReady fires. That means initial synchronization and editor readiness have completed, not that the server has saved the document. Call destroy() when your owning route or component unmounts to release the connection; the standalone example does this when the page closes.

Reopen or start over

To reopen the existing room, use a join address such as http://localhost:5173/?user=Alex. Reloading the original mode=create address tries to create the room again and fails.

To start over, restart the example server, then open the create address followed by the join address.

If the example shows Connection failed., inspect the error reported by onException. Check that the server is still running, both editors use the same documentId, and the creator reached Connected. before the joiner opened. A failed join is not a reason to overwrite the room with a local file.

Show who is editing

Next, add presence and cursors so Alex and Sam can identify each other while they work.

Configure transient recovery

The preview built-in Hocuspocus connection supports collaboration.retry without a custom worker or server migration:

const collaboration = {
  providerType: 'hocuspocus',
  documentId: 'example-room',
  serverUrl: 'ws://127.0.0.1:1234',
  retry: {
    reconnectMinDelayMs: 100,
    reconnectMaxDelayMs: 1000,
    delayMs: 1000,
    factor: 2,
    minDelayMs: 100,
    maxDelayMs: 30000,
    jitter: true,
  },
} satisfies DocumentCollaborationConfig;

These values are the defaults. After an established connection drops, each client independently samples an integer wait from 100 through 1000 milliseconds, inclusive. After the first failed attempt, the retry window is 100–1000 ms; later upper bounds grow to 2000, 4000, 8000, 16000 and then the 30000 ms cap. Calculated upper bounds are rounded down to integer milliseconds. Each wait uses a fresh sample, measured after that attempt fails. Individual waits need not increase. Successful recovery resets the retry window for the next outage.

All delay settings use integer milliseconds, bounded by 2147483647. Reconnect bounds may be zero; failed-attempt waits must be positive. Require reconnectMinDelayMs <= reconnectMaxDelayMs, minDelayMs <= delayMs <= maxDelayMs, a finite factor >= 1, and boolean jitter. Set jitter: false to select each window's upper bound for deterministic timing. Partial settings override the defaults and must still form valid ranges. Invalid settings fail with a configuration error before opening a connection. A retry-disable option is not supported.

A healthy first connection starts immediately; the reconnect window applies only after a connection has been established. syncTimeoutMs separately limits the initial synchronization wait. It does not configure retry delay or guarantee recovery within that duration. Transient failures retry automatically; authentication/permission rejection and explicit disconnect or destruction stop pending retries.

To verify with your existing Hocuspocus server, open two editors in the same room, record each client's socket-close and new-connection times, and interrupt their established transports while keeping the room's stored document intact. Keep the endpoint unavailable through each first failed reconnect, then restore it. Measure reconnect from the established close and retry from the failed attempt's close; server request times alone also include connection latency. The two windows should follow your settings, and edits and presence should resume without reloading. Repeat the interruption to observe fresh samples. Random samples can coincide, so a single pair of matching times does not establish shared scheduling. For a deterministic control, use jitter: false and a longer reconnect upper bound, then verify that a separate healthy first open remains prompt. The pinned example above does not include these preview settings.