Show HN: Hocuspocus 4 – self-hosted Yjs collaboration backend

The Quiet Revolution in Real-Time Collaboration: How Hocuspocus 4 is Redefining Self-Hosted Sync

In a world where Google Docs feels like magic—where two people can edit the same sentence at the same time without chaos—most users take the underlying technology for granted. But behind every seamless co-editing session lies a complex dance of data synchronization, conflict resolution, and real-time communication. Now, a new open-source tool is making that magic accessible to developers everywhere: Hocuspocus 4, a self-hosted collaboration backend built on the powerful Yjs CRDT framework.

Developed by Philip and the team at Tiptap—the creators behind one of the most popular open-source rich text editor ecosystems—Hocuspocus has quietly evolved over five years from an internal solution into a production-grade engine for real-time collaboration. With the release of version 4 under the MIT license, Hocuspocus has shed its Node.js shackles and embraced a truly universal runtime model, enabling developers to deploy collaborative backends anywhere—from edge servers to Deno environments.

This isn’t just another WebSocket wrapper. Hocuspocus is a full-featured collaboration server that handles everything from document synchronization to user presence, all while ensuring data consistency across distributed systems. And with its latest upgrade, it’s become more flexible, type-safe, and scalable than ever before.

The Problem with Real-Time Collaboration (And Why It’s Harder Than It Looks)

Real-time collaboration sounds simple: multiple users edit the same document, and changes appear instantly. But the reality is far more complex. When two people type simultaneously, how do you ensure their edits don’t overwrite each other? What happens when network latency causes one user’s changes to arrive out of order? These aren’t just technical hiccups—they’re fundamental challenges in distributed systems.

Traditional approaches often rely on Operational Transformation (OT), the algorithm pioneered by Google in Google Wave and later used in Google Docs. OT works by transforming operations (like “insert ‘hello’ at position 5”) so they can be applied in different orders without conflict. But OT is notoriously difficult to implement correctly, especially at scale. It requires a central server to manage transformation logic, and bugs can lead to data corruption or lost edits.

Enter Conflict-Free Replicated Data Types (CRDTs)—a newer, more robust approach to distributed data synchronization. Unlike OT, CRDTs don’t require a central authority to resolve conflicts. Instead, they use mathematical structures that guarantee consistency no matter the order of operations. Yjs, the CRDT library at the heart of Hocuspocus, is one of the fastest and most efficient implementations available.

Yjs allows multiple clients to make changes independently, and when those changes are synced, the CRDT automatically merges them without conflicts. This means developers don’t have to worry about race conditions or transformation logic—Yjs handles it all under the hood.

Hocuspocus: The Missing Link Between Yjs and the Real World

While Yjs is powerful, it’s primarily a client-side library. It doesn’t handle networking, authentication, or persistence. That’s where Hocuspocus comes in. Think of it as the “server glue” that turns Yjs into a full collaboration platform.

Hocuspocus acts as a WebSocket server that sits between your clients (like a web editor) and your backend. It manages real-time document sync, tracks which users are online (presence), stores document updates, and can scale horizontally using Redis. Whether you’re building a collaborative text editor, a shared whiteboard, or a multiplayer game state, Hocuspocus provides the infrastructure to keep everything in sync.

One of the most compelling aspects of Hocuspocus is its framework-agnostic design. It works with any editor that supports Yjs—whether you’re using Tiptap, ProseMirror, Slate, Quill, Monaco (used in VS Code), or even a custom-built editor. This flexibility has led to unexpected use cases, such as developers using Hocuspocus to sync configuration files across distributed systems or to power real-time dashboards with live data updates.

Breaking Free from Node.js: The Biggest Leap in Hocuspocus 4

For years, Hocuspocus was tightly coupled to Node.js, relying on the `ws` WebSocket library. While `ws` is fast and reliable, it’s Node-specific. That meant you couldn’t run Hocuspocus on modern JavaScript runtimes like Bun, Deno, or Cloudflare Workers—environments that offer better performance, lower latency, or edge deployment capabilities.

Version 4 changes everything. By replacing `ws` with crossws, a universal WebSocket adapter, Hocuspocus now runs seamlessly across all major JavaScript runtimes. This is a game-changer for developers who want to deploy collaboration features at the edge—closer to users for faster response times.

Imagine a collaborative editor deployed on Cloudflare Workers, where each user connects to the nearest edge node. Updates are processed locally and synced globally with minimal latency. Or a Deno-based microservice handling document persistence with built-in security and TypeScript support. These scenarios are now not just possible—they’re practical.

This shift also future-proofs Hocuspocus. As the JavaScript ecosystem evolves, Hocuspocus can adapt without rewriting core logic. It’s a move toward runtime portability, a trend gaining momentum in the developer community.

Type Safety and Correctness: Engineering for Production

Running a collaboration server in production isn’t just about syncing data—it’s about ensuring correctness, security, and maintainability. Hocuspocus 4 introduces several under-the-hood improvements that make it more robust for serious applications.

One of the most significant changes is the introduction of generic Context types. Previously, authentication and session data passed through hooks as loosely typed objects, making it easy to introduce bugs. Now, every core class and hook payload accepts a generic `Context` type, allowing developers to define their auth schema once and have it propagate with full TypeScript safety.

For example, if your `onAuthenticate` hook returns a user object with `id`, `role`, and `permissions`, that same typed object is available in every subsequent hook—like `onConnect`, `onLoadDocument`, or `onStoreDocument`. This eliminates type casting and reduces runtime errors.

Another critical fix addresses a subtle but dangerous bug: out-of-order CRDT updates under load. In earlier versions, asynchronous hooks (like database lookups or API calls) could delay processing, causing document updates to be applied in the wrong sequence. This violated the causal consistency guarantees of CRDTs and could lead to data divergence.

Hocuspocus 4 solves this with an internal queue per connection that processes updates sequentially. Even if a hook takes time, updates are queued and applied in the correct order, preserving data integrity.

The Wire Protocol: Backward Compatibility Without Compromise

Upgrading a production system is always risky. You can’t afford to break existing clients when rolling out a new server version. Hocuspocus 4 addresses this with a bidirectionally backward-compatible wire protocol.

This means you can upgrade your Hocuspocus server independently of your clients—and vice versa. A v3 client can connect to a v4 server, and a v4 client can connect to a v3 server, with no changes required. The protocol automatically negotiates compatibility, ensuring smooth transitions during deployments.

This is especially valuable for large organizations with distributed teams or third-party integrations. You can roll out updates incrementally, test in staging, and monitor performance—all without coordinating a synchronized release across all services.

Additionally, Hocuspocus now uses web-standard `Request` and `Headers` objects instead of Node’s `IncomingMessage`. This aligns with modern web APIs and makes it easier to integrate with middleware, authentication layers, and edge functions.

Real-World Impact: Who’s Using Hocuspocus (And Why It Matters)

While Tiptap uses Hocuspocus internally for its cloud-based editor, the tool has found a life of its own in the open-source ecosystem. Developers are using it to build everything from collaborative coding environments to real-time project management tools.

One notable example is a startup building a distributed design tool where multiple users edit vector graphics in real time. Because Yjs can sync structured data (not just text), they use Hocuspocus to sync SVG paths, layers, and metadata across users—all without a single conflict.

Another team used Hocuspocus to create a live configuration editor for DevOps teams. Instead of manually editing YAML files, engineers collaborate in a web interface, with changes instantly synced to version control. Hocuspocus handles the real-time sync, while hooks trigger CI/CD pipelines on document save.

The Future of Self-Hosted Collaboration

Hocuspocus 4 represents a shift in how we think about real-time collaboration. It’s no longer a feature reserved for tech giants with massive engineering teams. With open-source tools like Hocuspocus, any developer can add seamless, conflict-free collaboration to their app—without relying on third-party services.

The move to universal runtimes, combined with stronger type safety and production-grade reliability, positions Hocuspocus as a cornerstone of the next generation of collaborative software. Whether you’re building the next Google Docs or a niche tool for remote teams, Hocuspocus offers a powerful, flexible, and self-hosted solution.

As Philip and the Tiptap team continue to refine the stack, one thing is clear: the future of collaboration isn’t locked behind proprietary APIs. It’s open, modular, and ready to be self-hosted.

And the best part? You can try it today.

This article was curated from Show HN: Hocuspocus 4 – self-hosted Yjs collaboration backend via Hacker News (Top)