Real Time Collaboration: A Web App Engineering Primer

What you need to know

• WebSockets are the right transport for collaboration features. HTTP polling is inadequate for the update frequency that makes collaboration feel real-time.
• Do not implement conflict resolution from scratch. Use Yjs (CRDT-based) or ShareDB (OT-based). Both are production-tested and handle the edge cases that manual implementations miss.
• Presence (live cursors, online indicators) requires a heartbeat mechanism. Clients that disconnect without sending a goodbye message must be expired by the server on heartbeat timeout.
• Optimistic updates are required for the feature to feel responsive. Users should see their own changes immediately, before server confirmation.
• Scale testing matters more than unit testing for collaboration features. Bugs in conflict resolution often only appear under concurrent edits from multiple users.

The core argument

Real-time collaboration is one of the features that is easy to add for the simple case and genuinely difficult to implement correctly for the general case. A shared todo list where two users can add items simultaneously is straightforward: append-only operations commute, conflicts are trivially merged, and a simple WebSocket broadcast of operations works. A shared rich text document where two users can edit the same paragraph simultaneously requires a conflict resolution algorithm, and implementing that algorithm incorrectly produces corrupted documents in a small but non-zero fraction of concurrent edit scenarios.

The practical advice for most product teams is: use a library. Yjs is the production-ready CRDT library that powers collaborative features in products like Notion, Linear, and countless others. It handles conflict resolution, undo history, and presence, and has providers for multiple backends (WebSocket, WebRTC, IndexedDB for offline). The engineering work is integration, not algorithm implementation. A team that builds a custom OT algorithm to avoid Yjs's complexity will spend weeks on the algorithm and years fixing the edge cases Yjs has already solved.

The architecture that works for most SaaS collaboration features is: Yjs documents for shared document state, a WebSocket server (Hocuspocus is the standard Yjs WebSocket server) for synchronization, and awareness for presence data. The result is a synchronization layer that handles network partitions, reconnection, offline edits, and conflict resolution without requiring the product team to understand the implementation details.

Common mistakes

1. Using a database table as the collaboration store. Collaborative features require a real-time synchronization mechanism, not a polling loop that reads a database table every second. Database polling at the frequency required for responsive collaboration creates significant database load and still produces a 1-second latency minimum. WebSockets with an in-memory or Redis-backed state store is the correct architecture.

1. Not handling reconnection. WebSocket connections drop due to network interruptions, sleep/wake cycles, and server restarts. The client must reconnect automatically and resynchronize state after reconnection. Yjs handles this through its provider architecture, but custom WebSocket implementations must explicitly handle reconnection with backoff and state reconciliation.

1. Broadcasting all changes to all connected users. In a large collaborative application, not all users need all updates. A user editing document A should not receive updates for document B. Implement room or channel scoping so WebSocket broadcasts are targeted to the relevant connected clients.

1. Ignoring the conflict between optimistic updates and authoritative server state. Optimistic updates show local changes immediately. If the server rejects or transforms the operation, the local state must be corrected. Without this reconciliation, the user's local view diverges from the server state silently. Yjs's CRDT approach handles this naturally because the local and remote state always merge deterministically.

1. Not testing concurrent edit scenarios. Collaboration bugs are often specific to concurrent edits with specific timing. Manual testing with two browsers is insufficient for coverage. Write integration tests that simulate concurrent operations from multiple clients and verify the final merged state is correct.

Where to start

1. Choose the collaboration library before designing the data model. Yjs and ShareDB have different data model constraints. Yjs works with Y.Doc as the top-level data structure containing Y.Map, Y.Array, and Y.Text types. Design the collaborative data model in terms of the library's types before writing application code.

1. Deploy Hocuspocus (for Yjs) or ShareDB backend first without the frontend. Test the synchronization backend independently with a command-line client before building the frontend. Confirm that two clients can connect, make edits, and see each other's edits merged correctly.

1. Implement presence separately from document synchronization. Yjs Awareness handles presence data (cursor positions, user names, online status) independently from document state. Implement the presence visualization (colored cursors, user avatars in the toolbar) as a separate feature after document synchronization works correctly.

Related reading

• Next.js vs Remix vs Astro vs Nuxt in 2026
• React Query vs SWR vs RTK Query
• Offline First Mobile Apps: A Reality Check
• PostgreSQL Performance at Scale: The Tweaks That Move the Needle