Building Real-Time Collaborative Editors with WebSockets and CRDTs

1. Executive Summary & Problem Formulation

If you try to build a multiplayer text editor (like Google Docs) by syncing raw text strings between clients and a database, the system will collapse within seconds. If User A types "Hello" at the beginning of a document, and User B simultaneously types "World" at the end of the document, resolving whose keystroke goes where requires a distributed consensus mechanism.

Historically, this problem was solved using Operational Transformation (OT). OT requires a central server to intercept every single keystroke, order them mathematically, transform concurrent operations against each other, and broadcast the transformed results back to clients. While OT works, it forces you to write a massive, stateful Node.js backend. Furthermore, OT breaks down completely in offline scenarios or peer-to-peer (P2P) topologies where a central authority does not exist.

The modern solution is the Conflict-free Replicated Data Type (CRDT). CRDTs solve the synchronization problem purely through mathematical data structures that guarantee strong eventual consistency without requiring a central server. If two clients disconnect from the internet, edit the exact same paragraph for three hours, and then reconnect, the CRDT merges the changes flawlessly.

This guide explores the architectural implementation of a collaborative rich-text editor using WebSockets for network transport, Yjs as the CRDT state engine, and ProseMirror as the frontend view layer.

2. Mathematical & Architectural Theory

The Mechanics of a Sequence CRDT

A rich text document is fundamentally an ordered sequence of characters or blocks. To make this sequence collaborative without conflicts, we use a Sequence CRDT (like Yjs or Automerge).

Instead of identifying characters by integer array indices (e.g., the 'H' is at index 0, the 'e' is at index 1), a CRDT assigns a globally unique fractional identifier to every single character inserted.

Imagine User A types "CAT". The CRDT assigns identifiers based on the user's client ID and a logical clock (a Lamport timestamp). - 'C': (UserA, clock: 1) - 'A': (UserA, clock: 2) - 'T': (UserA, clock: 3)

These identifiers are ordered lexicographically. If User B wants to insert an 'H' between 'C' and 'A', the local CRDT calculates a mathematical identifier that perfectly falls between clock 1 and clock 2 (e.g., 1.5). - 'H': (UserB, clock: 1) is inserted exactly after (UserA, 1) and before (UserA, 2).

Because these identifiers are globally unique and absolutely ordered, any two clients receiving the same set of insertion/deletion commands—regardless of the order they arrive over the network—will mathematically converge on the exact same final document state.

The Yjs Ecosystem Architecture

Yjs is the industry-standard CRDT implementation for JavaScript. It optimizes the fractional indexing problem using a doubly-linked list of Item blocks combined with a highly compressed binary encoding format.

A collaborative editor architecture using Yjs consists of three isolated layers: 1. The Shared Type (State): A Y.Doc instance running in memory on the client. It exposes data structures like Y.Text or Y.Map. 2. The Provider (Network): A transport layer that observes the Y.Doc for changes, serializes the differential state updates into Uint8Array binary blobs, and broadcasts them via WebSockets, WebRTC, or IndexedDB. 3. The Binding (View): A synchronization bridge that maps the Y.Text state bidirectionally into the DOM state of a UI framework like React, CodeMirror, or ProseMirror.

3. Concrete Implementation: WebSocket and Yjs Integration

Below is a barebones implementation of a collaborative editor architecture. We configure a WebSocket server using Node.js and the y-websocket package to act as a dumb relay. We then configure the client-side JavaScript to bind a ProseMirror text editor to the Yjs document state.

Unlike an OT backend, notice how the Node.js server contains zero conflict resolution logic. It simply receives binary CRDT updates and broadcasts them to connected peers.

// ==========================================
// 1. BACKEND: WebSocket Relay Server (Node.js)
// ==========================================
const WebSocket = require('ws');
const http = require('http');
const { setupWSConnection } = require('y-websocket/bin/utils');

const server = http.createServer((request, response) => {
    response.writeHead(200, { 'Content-Type': 'text/plain' });
    response.end('CRDT WebSocket Server Active');
});

const wss = new WebSocket.Server({ server });

wss.on('connection', (conn, req) => {
    // The setupWSConnection function handles standard Yjs binary sync protocol
    // It maintains the document state in memory and broadcasts updates to all peers
    setupWSConnection(conn, req, { gc: true });
});

server.listen(1234, () => {
    console.log('Listening on port 1234');
});

// ==========================================
// 2. FRONTEND: Client-side Editor Binding
// ==========================================
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
import { EditorState } from 'prosemirror-state';
import { EditorView } from 'prosemirror-view';
import { schema } from 'prosemirror-schema-basic';
import { ySyncPlugin, yCursorPlugin, yUndoPlugin, undo, redo } from 'y-prosemirror';
import { keymap } from 'prosemirror-keymap';

// 1. Initialize the local CRDT state
const ydoc = new Y.Doc();
const type = ydoc.getXmlFragment('prosemirror');

// 2. Connect to the WebSocket relay server
// 'my-document-id' acts as the room/channel identifier
const provider = new WebsocketProvider(
    'ws://localhost:1234',
    'my-document-id',
    ydoc
);

// Optional: Assign a random color and name for presence cursors
provider.awareness.setLocalStateField('user', {
    name: `User ${Math.floor(Math.random() * 100)}`,
    color: '#' + Math.floor(Math.random()*16777215).toString(16)
});

// 3. Configure the ProseMirror view layer
const editorNode = document.querySelector('#editor');

const view = new EditorView(editorNode, {
    state: EditorState.create({
        schema,
        plugins: [
            // ySyncPlugin maps ProseMirror DOM changes to Yjs CRDT operations
            ySyncPlugin(type),
            // yCursorPlugin renders remote user cursors based on awareness data
            yCursorPlugin(provider.awareness),
            yUndoPlugin(),
            keymap({
                'Mod-z': undo,
                'Mod-y': redo,
                'Mod-Shift-z': redo
            })
        ]
    })
});

// Handle connection status UI
provider.on('status', event => {
    console.log(`WebSocket Status: ${event.status}`); // 'connected' or 'disconnected'
});

4. Edge Cases, Optimization & Memory Considerations

CRDT Memory Bloat and Garbage Collection

Because a CRDT must mathematically resolve concurrent insertions that happened hours apart, it must theoretically preserve the metadata of every single deleted character (known as tombstones). In a text document edited continuously for two years, the tombstone data structure will outgrow the visible text size by a factor of 100. The browser tab will crash due to V8 heap exhaustion.

Yjs mitigates this via its Garbage Collection (GC) mechanism. When all connected peers confirm they have received a deletion operation, the Yjs engine mathematically prunes the tombstone, squashing the logical clocks together to compress the internal doubly-linked list. However, if a user goes offline for three days, the system must retain tombstones on the server until that user reconnects and syncs. Always enable { gc: true } on your WebSocket provider.

The Awareness Protocol (Presence and Cursors)

Synchronizing the physical text is handled by the core Y.Doc. However, synchronizing ephemeral UI state—like remote cursors, selections, and "User is typing..." indicators—should never be stored in the CRDT document. If a user moves their mouse 60 times a second, writing that into the CRDT history will bloat the document irreparably.

The y-websocket provider exposes an out-of-band provider.awareness object. This implements an ephemeral state-sync protocol utilizing a simple last-writer-wins mechanism. Awareness data automatically evaporates when a WebSocket connection drops, ensuring stale cursors do not litter the document.

Persistent Offline Storage

A pure WebSocket implementation loses all document state if the Node.js server restarts and all clients are currently disconnected. You must persist the Y.Doc binary state to a database.

On the client side, attach a y-indexeddb provider to the exact same ydoc instance.

import { IndexeddbPersistence } from 'y-indexeddb';
const indexeddbProvider = new IndexeddbPersistence('my-document-id', ydoc);

This forces the CRDT to dump its state into the browser's local IndexedDB. When the user reloads the page on an airplane with no WiFi, the IndexedDB provider instantly loads the document, the user edits it locally, and the WebSocket provider syncs the delta changes exactly once connectivity is restored.

5. Benchmarks & Practical Engineering Takeaways

We benchmarked Yjs CRDT operations against an Operational Transformation fallback on a 50,000-word document with 10 concurrent active typing sessions.

Engineering Guidelines

• Avoid stringifying CRDT state: Never call ydoc.getText().toString() repeatedly inside a React useEffect or Vue computed property to trigger UI updates. The CRDT data structure is complex. Recomputing the full raw string on every keystroke causes massive CPU frame drops. Rely on the direct view bindings (y-prosemirror, y-monaco).
• Binary formats over JSON: The Y.encodeStateAsUpdate(ydoc) function outputs a highly optimized Uint8Array. If you must store this in a relational PostgreSQL database, store it in a BYTEA or BLOB column. Do not convert the binary array into a Base64 string to store in a JSON field, as this inflates the payload size by 33%.
• Scale WebSocket connections: The Node.js WebSocket relay is entirely CPU-bound by message broadcasting. Once you hit 5,000 concurrent sockets, a single Node thread will lock. You must horizontally scale the WebSocket servers and link them via a Redis Pub/Sub backplane using the @hocuspocus/server architecture.

6. References & Cross-Links

• Shapiro, M., Preguiça, N., Baquero, C., & Zawirski, M. (2011). Conflict-Free Replicated Data Types. Symposium on Self-Stabilizing Systems.
• Yjs Official Documentation: Yjs - A CRDT framework with a powerful ecosystem.
• Susam, A. (2026). Advanced IndexedDB Strategies for Gigabyte-Scale Offline Caching. Read Article.
• Susam, A. (2026). Handling Large Binary Buffers in Client-Side JavaScript. Read Article.