@hocuspocus/provider

@hocuspocus/provider

The client-side provider for Hocuspocus. Connects to a Hocuspocus server over WebSockets and syncs one or more Y.js documents — including awareness (presence), authentication, and stateless messaging.

Building a React app? Use @hocuspocus/provider-react instead — it wraps the provider in components and hooks so React handles the lifecycle for you (including StrictMode double-mounts).

Installation

npm install @hocuspocus/provider yjs

Usage

import * as Y from "yjs"
import { HocuspocusProvider } from "@hocuspocus/provider"

const ydoc = new Y.Doc()

const provider = new HocuspocusProvider({
  url: "ws://127.0.0.1:1234",
  name: "example-document",
  document: ydoc,
})

Changes to ydoc are now synced to every other client connected to the same name.

Authenticating

Pass a token — it's forwarded to the server's onAuthenticate hook:

new HocuspocusProvider({
  url: "wss://collab.example.com",
  name: "example-document",
  document: ydoc,
  token: "super-secret-token",
})

Sharing a socket across documents

Create a HocuspocusProviderWebsocket once, then reuse it for multiple documents:

import {
  HocuspocusProvider,
  HocuspocusProviderWebsocket,
} from "@hocuspocus/provider"

const socket = new HocuspocusProviderWebsocket({ url: "ws://127.0.0.1:1234" })

const doc1 = new HocuspocusProvider({ websocketProvider: socket, name: "doc-1" })
const doc2 = new HocuspocusProvider({ websocketProvider: socket, name: "doc-2" })

Call provider.destroy() to disconnect a single document. Call socket.destroy() to tear down the shared connection.

Documentation

Full configuration, events, and awareness reference: tiptap.dev/docs/hocuspocus/provider.

License

MIT — see LICENSE.md.

Similar packages

Other packages similar to @hocuspocus/provider

y-websocket

y-websocket is a WebSocket provider for Yjs that enables real-time collaboration over WebSocket connections. It is similar to @hocuspocus/provider in that it facilitates the synchronization of Yjs documents across clients. However, @hocuspocus/provider offers additional features such as awareness states and a more flexible API for handling connections and events.

sharedb

ShareDB is a real-time database backend based on Operational Transformation (OT) that allows for collaborative editing. While it provides similar real-time collaboration capabilities, it uses a different algorithm (OT vs. CRDT) and is not specifically designed to work with Yjs. ShareDB is more focused on providing a backend for real-time applications, whereas @hocuspocus/provider is tailored for use with Yjs and CRDTs.

automerge

Automerge is a library for building collaborative applications using CRDTs. Like @hocuspocus/provider, it enables real-time collaboration, but it is a more general-purpose CRDT library that does not include built-in networking capabilities. Developers need to implement their own networking layer to synchronize changes between clients.