Hocuspocus

Hocuspocus is a collaboration backend built on Yjs, a CRDT (conflict-free replicated data type) library, that lets multiple clients edit the same document in real time over WebSockets with automatic conflict resolution. @hocuspocus/server is the core server package — instantiate a Server, wire in lifecycle hooks (onConnect, onLoadDocument, onStoreDocument, onChange), and it handles syncing Yjs document updates between all connected clients.

The rest of the monorepo builds around that server core: @hocuspocus/provider is the matching client-side connector (commonly paired with editors like Tiptap or ProseMirror), and a family of extension packages (extension-database, extension-redis, extension-s3, extension-sqlite, extension-webhook, extension-throttle, extension-logger) add persistence, horizontal scaling, and observability without touching the core server code. Maintained by Tiptap, which also offers a paid managed cloud version (Tiptap Collab) for teams that don’t want to self-host.

What You Get

• A Server class that accepts WebSocket connections and syncs Yjs document updates between all connected clients automatically
• A hook-based extension system (onConnect, onAuthenticate, onLoadDocument, onStoreDocument, onChange) for wiring in auth, persistence, and custom logic
• Official extension packages for SQLite, Redis (horizontal scaling across server instances), S3, database persistence, webhooks, throttling, and logging
• A companion @hocuspocus/provider client package and @hocuspocus/transformer for converting between Yjs docs and ProseMirror/Tiptap JSON

Common Use Cases

• Building real-time collaborative rich-text editors (commonly paired with Tiptap or ProseMirror via the transformer package)
• Persisting collaborative documents to a database or S3 via the official extension packages instead of writing custom storage logic
• Scaling collaboration servers horizontally across multiple instances using the Redis extension for shared awareness/state
• Adding authentication and per-document access control via the onAuthenticate/onConnect hooks before allowing a client to join a document

Under The Hood

Architecture — The Hocuspocus class (packages/server/src/Hocuspocus.ts, ~650 lines) is the central orchestrator: it manages Document instances (each wrapping a Yjs Y.Doc), tracks Connection/ClientConnection objects per WebSocket client, and dispatches the full hook lifecycle to registered extensions on every connect, message, and disconnect event. MessageReceiver and IncomingMessage/OutgoingMessage implement the Yjs sync protocol’s binary message framing over the WebSocket transport, while DirectConnection allows server-side code to read/write a document without an actual client connection (useful for webhooks or migrations).

Tech Stack — TypeScript throughout (98%), structured as a pnpm monorepo where the server core has zero required persistence dependency — SQLite, Redis, S3, and generic database persistence are all separate extension-* packages a consumer opts into. The core depends directly on yjs and ws (or a compatible WebSocket implementation); extensions bring their own client libraries (ioredis for Redis, aws-sdk/@aws-sdk/client-s3 for S3, etc.).

Code Quality — A dedicated tests/ workspace package holds integration-style test suites per concern (server/, provider/, providerwebsocket/, transformer/, extension-redis/, extension-s3/, extension-throttle/), exercising real client/server WebSocket round-trips rather than only mocking Yjs internals — notable for a real-time system where message-ordering and reconnect edge cases are easy to miss with pure unit tests. Sustained release cadence (99 tagged releases, ~13 commits/month) and 83 contributors indicate active maintenance.

API Design — The hook-based extension model (onConnect, onLoadDocument, onStoreDocument, etc., each an async function on a plain object or class instance passed into extensions: []) is the core design decision: it keeps the server itself persistence-agnostic and lets teams compose exactly the extensions they need (e.g. SQLite for a hobby project, Redis + S3 for production scale) without forking the server. The trade-off is that getting a fully working, persisted deployment requires understanding and composing several packages rather than one all-in-one server.