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
TheHocuspocusProviderWebsocket 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.Method 1: Sub-protocol (Recommended)
When initializing theHocuspocusProviderWebsocket, 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 theydoc 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 samewebsocketProvider instance for multiple HocuspocusProvider calls.

