upstream-hocuspocus/packages/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.