TopGit
GitHub Repo Review

Hocuspocus: Yjs Collaboration Backend

ueberdosis/hocuspocus
HTopGit review image for ueberdosis/hocuspocus
Review by Topgit.dev for ueberdosis/hocuspocus, with GitHub repository stats and README context.
Quick verdict

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.

Stars
โ˜… 2.7k
Forks
โ‘‚ 233
Contributors
๐Ÿ‘ฅ 83
Language
TypeScript
License
MIT
Topic
โ€”
Updated
Nov 2026

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.
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history โ†—

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

Tiptap Collab โ€” the official hosted version of Hocuspocus, per the README's Cloud Hosting section, for teams that don't want to run the WebSocket server.y-websocket โ€” the minimal reference WebSocket server that ships alongside Yjs itself, a lighter starting point if you don't need Hocuspocus's extension system.Liveblocks โ€” a hosted real-time collaboration API that runs the backend for you instead of a self-hosted Yjs server.ShareDB โ€” a real-time sync engine built on operational transformation instead of CRDTs, a different consistency model than Yjs and Hocuspocus.

Frequently Asked Questions

What is the license for Hocuspocus?

Hocuspocus is released under the MIT License, per its LICENSE.md file and GitHub's license listing for the repository.

How does Hocuspocus ensure conflict-free collaboration?

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.

Can Hocuspocus be self-hosted?

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.

Does Hocuspocus offer a cloud-hosted solution?

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.

What frontend editors are compatible with Hocuspocus?

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.

Where can I find community support for Hocuspocus?

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

Source & attribution

Facts and quotes sourced from the ueberdosis/hocuspocus GitHub repository and its README.

GitHub data ยท last synced Aug 12, 2026Reviewed by Henry
โ† Back to TopGit

Still deciding about hocuspocus?

One click hands the question to an AI along with this page โ€” see what it says about hocuspocus.

GitHub