Hocuspocus Provider Events

Introduction

Events are a great way to react to different states, for example when the provider has successfully connected. You can choose to bind event listeners on initialization or later, that’s up to you.

Option 1: Configuration

Passing event listeners to the constructor ensures they are registered during initialization.

const provider = new HocuspocusProvider({
  url: "ws://127.0.0.1:1234",
  name: "example-document",
  document: ydoc,
  onOpen() {
    // …
  },
  onConnect() {
    // …
  },
  onAuthenticated() {
    // …
  },
  onAuthenticationFailed: ({ reason }) => {
    // …
  },
  onStatus: ({ status }) => {
    // …
  },
  onMessage: ({ event, message }) => {
    // …
  },
  onOutgoingMessage: ({ message }) => {
    // …
  },
  onSynced: ({ state }) => {
    // …
  },
  onClose: ({ event }) => {
    // `event` has `code` and `reason` (since v4)
    // …
  },
  onDisconnect: ({ event }) => {
    // …
  },
  onDestroy() {
    // …
  },
  onAwarenessUpdate: ({ added, updated, removed }) => {
    // …
  },
  onAwarenessChange: ({ states }) => {
    // …
  },
  onStateless: ({ payload }) => {
    // ...
    // the provider can also send a custom message to the server: provider.sendStateless('any string payload')
  },
  onMaxAttemptsFailed: ({ error }) => {
    // Only relevant if you set `maxAttempts`. Handled by the underlying
    // HocuspocusProviderWebsocket – see the section below.
  }
});

Option 2: Binding

Sometimes you want to register an event listener after the initialization, even if it’s right after. Also, that’s a great way to bind and unbind event listeners.

Bind event listeners

const provider = new HocuspocusProvider({
  // …
});

provider.on("synced", () => {
  // …
});

Unbind event listeners

const onMessage = () => {
  // A new message comes in
};

// Bind …
provider.on("onMessage", onMessage);

// … and unbind.
provider.off("onMessage", onMessage);

List of events

Name	Description
open	When the WebSocket connection is created.
connect	When the provider has successfully connected to the server.
authenticated	When the client has successfully authenticated.
authenticationFailed	When the client authentication was not successful.
status	When the connections status changes.
message	When a message is incoming.
outgoingMessage	When a message will be sent.
synced	When the Y.js document is successfully synced (initially).
close	When the WebSocket connection is closed.
disconnect	When the provider disconnects.
destroy	When the provider will be destroyed.
awarenessUpdate	When the awareness updates (see https://docs.yjs.dev/api/about-awareness)
awarenessChange	When the awareness changes (see https://docs.yjs.dev/api/about-awareness)
stateless	When the stateless message was received.

HocuspocusProviderWebsocket events

The events above belong to the HocuspocusProvider, which represents a single document. The WebSocket connection underneath it — a HocuspocusProviderWebsocket, potentially shared by several documents — has one event of its own:

Name	Description
maxAttemptsFailed	When all `maxAttempts` reconnect attempts have failed and the provider stops retrying.

It is not forwarded to the document providers, so bind it on the socket:

provider.configuration.websocketProvider.on("maxAttemptsFailed", ({ error }) => {
  // …
});

Passing onMaxAttemptsFailed to the HocuspocusProvider constructor works as well, as long as you let the provider create its own socket. See Reacting to failed reconnects.

PreviouslyConfiguration

Next upReact