Host the shared record
import { createCollaborationService } from "@onodocs/sdk/collaboration";
const service = createCollaborationService({
licenseKey,
authorize: async (documentId, context) => documentPermission(documentId, await authenticate(context)),
storage: {
load: documentId => loadSharedRecord(documentId),
receipt: (documentId, userId, mutationId) => loadReceipt(documentId, userId, mutationId),
compareExchange: (documentId, token, next, receipt) => commitSharedRecord(documentId, token, next, receipt)
}
});The callbacks are application-owned. Authorization returns { id, name, role } with edit, review or view, or undefined to deny. It runs on reads and writes, including before commit. Supply the application license on service and browser.
Store bytes, an opaque token and a structural checkpoint. Initialize tokens with separate UUIDs. compareExchange must atomically store the next record and receipt only when the stored token matches; return false otherwise. Retain indexed receipts while clients may recover old drafts. The SQLite example implements this contract.
Expose an authenticated exchange
Route authenticated POST requests to service.exchange(documentId, requestBody, context) and return its JSON reply. Derive document identity and user context from routing/authentication, enforce your origin/CSRF policy and map CollaborationAccessError to HTTP 403. Browser-supplied names and roles are not authority.
Open a shared editor
import { openCollaborativeEditor, createCollaborationTransport, createCollaborationRecovery } from "@onodocs/editor/collaboration";
const session = await openCollaborativeEditor({
container,
editor: { document: { licenseKey } },
exchange: createCollaborationTransport(`/documents/${documentId}/collaboration`),
recovery: createCollaborationRecovery(`${documentId}:${userId}:${tabId}`),
onError: showConnectionError
});Use a safe route identifier and an empty, sized host. Keep tabId in session storage so independent tabs keep separate drafts. Automatic polling synchronizes the session; session.sync() requests an immediate reconnect. Dispose when leaving. Use the session editor for mutations so they enter its journal.
Handle conflicts and disconnections
Edits to different unchanged paragraphs can merge. Same-paragraph, stale formatting/structure and stale review changes require a user choice. The local DOCX remains available for download, explicit discard for the shared copy, or authorized replacement against an unchanged server token.
Shared checkpoints clear local snapshot Undo so it cannot restore a pre-colleague document. Presence and peer selections follow document tokens; stale positions disappear. Offline draft recovery does not grant permission to publish. Failed durable recovery writes are reported while the in-memory draft remains downloadable.
Ordinary browser editing needs no collaboration server. See deployment and application licensing.