Run a collaboration server
Choose a provider and connect room access, storage, and recovery before deployment.
The two-editor example already runs a Hocuspocus server. Keep it for local development. Before deployment, choose who operates the provider and how rooms are authorized, saved, and recovered.
Run the server separately
The collaboration example pins Hocuspocus 2.15.3. Its pnpm dev command
starts both the browser app and server. You do not need a second server process.
To run only the server, stop pnpm dev, then run this from the example directory:
pnpm exec tsx server.tsThe example listens on port 1234 and keeps rooms in memory. Restarting the process clears them. With no storage integration, unloading a room after its last editor disconnects also loses its state.
Start the browser app separately with pnpm exec vite, or return to pnpm dev after stopping the standalone server.
Use the two-editor walkthrough to check the
connection. For storage, pass COLLABORATION_STORAGE_DIR to the server command. For the access example, pass
COLLABORATION_DEMO_AUTH=1 to the server command and VITE_COLLABORATION_DEMO_AUTH=1 to the Vite command.
The default commands enable neither storage nor access checks.
Prepare for production
Choose a provider
Hocuspocus is the local example's default, not a requirement. The document's collaboration field accepts these targets through DocumentCollaborationConfig in the preview API:
providerType | Room and connection | Authentication |
|---|---|---|
'hocuspocus' | documentId and serverUrl (or url) | token or string params |
'y-websocket' | documentId and serverUrl (or url) | String params forwarded to your server |
'liveblocks' | documentId or roomId | Exactly one of authEndpoint or publicApiKey |
For Liveblocks, use an authenticated endpoint when access must be checked per room; a public key does not provide that check. Configure the chosen provider's server or service before pointing the editor at it. SuperDoc owns the browser connection and local shared state; pass connection settings, not an external { ydoc, provider } pair.
Authorize access
The minimal server deliberately has no authentication or durable storage. Before deployment, authenticate the WebSocket connection, authorize each room, persist room updates, set connection and document limits, and define backup and recovery behavior in the server layer.
Control access to a room demonstrates credential validation and per-room permission checks. Your server owns authorization; browser controls and display identity do not enforce it.
Initialize the document
Initialize a shared document explains who imports the DOCX, when to create or join, and how browser and backend initialization differ. The Hocuspocus server transports and stores shared state; it does not import the DOCX itself.
Persist the room separately from DOCX files
Save and restore a room shows how to store binary Yjs state, restart the server, and reopen with edits intact. It also explains why DOCX exports and presence are separate from room storage.
If your application starts with a local document, upgrade it to collaboration when someone invites another person to edit.