Hocuspocus: Yjs Collaboration Backend
Hocuspocus is a WebSocket backend that syncs Yjs CRDT documents between clients so multiple people can edit the same document without merge conflicts. It ships as a plug & play server you run yourself, with SQLite persistence wired up in the README's own example and Tiptap Collab as a hosted fallback. Reach for it if you're building on Yjs and want a server you control; skip it if you need a turnkey hosted API instead of a Node process to run.
What is Hocuspocus?
Hocuspocus is an open-source WebSocket backend, written in TypeScript, that connects Yjs CRDT documents across clients so edits merge without conflict in real time. It sits between your frontend editor and whatever storage layer you plug in through its extension system, such as the bundled SQLite extension shown in the README. The repo's own GitHub topics tag it with prosemirror, slatejs, and tiptap alongside yjs and crdt, and it's MIT licensed.
Simplifying Real-time Collaboration
Yjs gives you a CRDT for merging document edits, but it doesn't ship a server โ you still have to write the WebSocket handling, persistence, and connection-lifecycle code that syncs Yjs documents between clients. Hocuspocus is that missing piece: a backend built specifically around Y.js that handles the WebSocket layer and exposes hooks like onConnect, so you're not writing a sync server from scratch every time you add collaborative editing to an app.
Core Features and Capabilities
- โA WebSocket server purpose-built for Yjs โ the README frames it as a ready-to-run collaboration server rather than a toolkit you assemble from scratch.
- โAn extension system for persistence: the README's usage example wires in the @hocuspocus/extension-sqlite package to write documents to a db.sqlite file.
- โLifecycle hooks like onConnect run your own code when a client connects โ logging, auth checks, or whatever else you need at the WebSocket layer.
- โListens on http://127.0.0.1 by default (ws:// for the WebSocket protocol), with the port set in the Server constructor โ 1234 in the README's example.
- โTagged self-hosted on GitHub, with Tiptap Collab as the official hosted alternative if you'd rather not run the server yourself.
- โInitial version written by kris, with contributions credited to Tom Moor and YousefED of TypeCellOS in the README's Contributors section.
Setting Up a Hocuspocus Server
The README's own example spins up a server with the Server class imported from @hocuspocus/server, listening on port 1234. You register extensions in an array โ the example uses the SQLite extension pointed at a db.sqlite file, so documents persist to a local file without you writing storage code yourself. An async onConnect hook fires when a client connects, which is where you'd add logic like an auth check before Hocuspocus completes the connection. Call .listen() and the server is live; point a Yjs-aware editor's WebSocket provider at it and edits start syncing.
Strengths
- โPurpose-built for Yjs rather than a generic pub/sub layer โ the WebSocket handling and CRDT sync are already wired together, per the README's own description.
- โThe README's usage sample is a runnable server with persistence included, not just an API reference.
- โRunning it yourself means documents never have to leave your own infrastructure โ Tiptap Collab exists as a fallback if you'd rather hand that off later.
- โMIT licensed, so there's no license friction for commercial use.
- โBacked by named sponsors โ including Cargo, Saga, Gamma, Outline, Ahrefs, Brickdoc, Sana, and Poggio, per the README's Sponsors section โ and an active Tiptap team behind it.
Considerations for Deployment
- โณThe README doesn't document install commands directly โ you infer the package names from the import statements in its usage example, not from a dedicated install section.
- โณFull documentation lives off-repo at the Tiptap docs site, so anything beyond this README and its one usage example isn't verifiable from the facts here.
- โณThe bundled example only demonstrates SQLite persistence; the README doesn't state which other storage backends ship as extensions.
- โณNo version number or changelog appears in the README, so there's no documented sense of release cadence from the repo facts alone.
- โณAuth, scaling, and production-hardening aren't covered in the README โ the only lifecycle hook shown is onConnect, with everything else deferred to Tiptap's separate documentation.
Cloud Hosting and Other Options
Frequently Asked Questions
Hocuspocus is released under the MIT License, per its LICENSE.md file and GitHub's license listing for the repository.
Hocuspocus syncs documents using Y.js, a CRDT, so edits from multiple clients merge automatically without conflicts. The README describes Hocuspocus itself as the WebSocket backend built specifically around that CRDT.
Hocuspocus can be self-hosted โ it's tagged self-hosted on GitHub, and the README's usage example runs the server yourself via the Server class from @hocuspocus/server, not a managed service.
Hocuspocus's README points to Tiptap Collab as the official cloud-hosted option, for teams that want to use Hocuspocus without operating the WebSocket server themselves.
The README doesn't list compatible editors in prose, but the repo's own GitHub topics tag it with prosemirror, slatejs, and tiptap alongside yjs, since Hocuspocus syncs whatever editor produces Yjs documents on the client.
Hocuspocus's README directs questions and feedback to [email protected], a GitHub issue, or the Tiptap Discord server, which it links directly for community discussion.
Best use cases
- โขAdding live co-editing to a Tiptap-based rich text editor without hand-rolling a WebSocket sync server.
- โขWiring up conflict-free multi-user editing for a ProseMirror or Slate.js based editor, since the repo's own GitHub topics tag it for both.
- โขPrototyping collaborative editing locally with the bundled SQLite extension before committing to a bigger database.
- โขSelf-hosting a collaboration backend instead of routing documents through a third-party API's servers.
How to install / try
The README doesn't include an explicit install command โ no npm install, yarn add, or pnpm add line appears anywhere in it. What you can infer from the usage example: the server ships as the @hocuspocus/server package, and persistence extensions like @hocuspocus/extension-sqlite are separate packages you add as needed. For the full setup path, the README points to the documentation at hocuspocus.dev/introduction rather than covering installation directly here.
Who should try it โ and who should skip
Try Hocuspocus if you're already building on Yjs โ especially with Tiptap, ProseMirror, or Slate.js โ and want a WebSocket server you run and own rather than assembling one from Yjs's lower-level pieces yourself. Skip it if you don't want to operate a Node server at all: Tiptap Collab, the README's own hosted offering, or a fully managed third-party collaboration API removes that operational piece entirely.
Related repositories
Still deciding about hocuspocus?
One click hands the question to an AI along with this page โ see what it says about hocuspocus.
