Skip to main content
WireSocket is compatible with any application that uses Y.js for state management. While you can use the standard y-websocket provider, we recommend the @hocuspocus/provider for robust synchronization, awareness (user presence), and easy integration with modern frameworks.
Editor-Agnostic: HocuspocusProvider is not tied to any specific editor. It manages Y.Doc instances directly, meaning it works with Tiptap, BlockSuite, Milkdown, or even custom canvas and form-based applications.

Installation

Install the provider and the core Y.js library:

Basic Setup

Connecting involves two steps: creating a dedicated WebSocket manager and then initializing a provider for your specific document.

1. Initialize WebSocket Provider

The HocuspocusProviderWebsocket manages the underlying connection to a WireSocket node.

2. Configure HocuspocusProvider

The provider handles document-specific synchronization and awareness.

Authentication Patterns

WireSocket recommends passing your JWT via the WebSocket sub-protocol to keep tokens out of server logs and browser history. When initializing the HocuspocusProviderWebsocket, you can define custom parameters for the handshake.

Method 2: Query Parameter

Alternatively, pass the token directly in the connection URL:

Awareness (User Presence)

Tracking cursors, user names, and colors is built into the provider. Awareness data is ephemeral and synchronized in real-time.

Editor Integrations

Tiptap (Example)

For Tiptap, simply pass the ydoc from your provider to the Collaboration extension.

React Pattern

When using React, ensure you manage the provider lifecycle to prevent memory leaks and duplicate connections.

Advanced: Connection Pooling

You can share a single WebSocket connection across multiple documents by using the same websocketProvider instance for multiple HocuspocusProvider calls.
Last modified on March 3, 2026