tiptap/docs/collaboration/provider.md

What is the Collaboration Provider

Together with the Collaboration backend, Providers act as the backbone for real-time collaborative editing. They establish and manage the communication channels between different users, ensuring that updates and changes to documents are synchronized across all participants.

Providers help handle the complexities of real-time data exchange, including conflict resolution, network reliability, and user presence awareness. The Hocuspocus provider, specifically designed for Tiptap Collaboration, brings advanced features tailored for collaborative environments, including WebSocket message authentication, debug modes, and flexible connection strategies.

Setting up a basic configuration

First you need to install the provider package in your project with

npm install @hocuspocus/provider

For a basic setup, you need to connect to the Collaboration backend. This involves specifying the document's name, your app's ID (for cloud setups), or the base URL (for on-premises solutions), along with your JWT. Depending on your framework, register a callback to the Collaboration backend, such as useEffect() in React or onMounted() in Vue.

  const doc = new Y.Doc()

  useEffect(() => {
    const provider = new TiptapCollabProvider({
      name: note.id, // Document identifier
      appId: 'YOUR_APP_ID', // replace with YOUR_APP_ID from Cloud dashboard
      token: 'YOUR_JWT', // Authentication token
      document: doc,
    })

Configuring an advanced provider

Tiptap Collaboration's advanced provider settings offer deep customization for enhanced collaboration. Below, explore a comprehensive list of parameters, practical use cases, and key concepts like "awareness" explained in detail.

Setting	Description	Default Value
appId	App ID for Collaboration Cloud setups.	''
baseUrl	URL for connecting to on-premises servers, used as an alternative to appId for on-prem setups.	''
name	The name of the document.	''
document	The Y.js document instance; defaults to creating a new one.	new Y.Doc()
token	Authentication token for secure connections. Works with strings, functions and Promises.	''
awareness	Manages user presence information, by default attached to the passed Y.js document.	new Awareness()
connect	Whether to connect to the server after initialization.	true
preserveConnection	Whether to preserve the websocket connection after closing the provider.	true
broadcast	Enables syncing across browser tabs.	true
forceSyncInterval	Interval for forced server sync (in ms).	false
quiet	Suppresses warning outputs.	false
WebSocketPolyfill	WebSocket implementation for Node.js environments. For example ws.	WebSocket

Optimizing Reconnection Timings

The provider’s reconnection settings are preset for optimal performance in production settings, ensuring reliability and efficiency. If you need to tweak these settings for specific scenarios, our delay configurations offer flexibility.

Adjust initial delays, apply exponential backoff, or set maximum wait times to fine-tune your application's reconnection behavior, balancing responsiveness with server efficiency.

delay	Base delay between reconnection attempts, in milliseconds.	1000
factor	Multiplier for delay, increasing it exponentially after each attempt.	2
initialDelay	Time before the first reconnection attempt, in milliseconds. Ideally immediate.	0
maxAttempts	Maximum number of reconnection attempts. 0 means unlimited.	0
jitter	When jitter is enabled, it adds variability to the reconnection delay by selecting a random value within the range of minDelay and the delay calculated for the current attempt.	true
minDelay	Minimum delay when jitter is enabled, ensuring a random delay isn't too short. This property has no effect if jitter is disabled.	1000
maxDelay	The maxDelay setting caps the delay during reconnection attempts. When using the exponential backoff (factor), you can specify 0 for maxDelay to remove this upper limit, allowing the delay to increase indefinitely.	30000
timeout	Sets a limit, in milliseconds, for how long to wait for a reconnection attempt before giving up. If this timeout is reached, subsequent attempts are halted.	0
messageReconnectTimeout	Defines the duration in milliseconds to await a server message before terminating the connection. If no message is received within this period, the connection is automatically closed.	30000