Integrate 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 TiptapCollabProvider provider adds advanced features tailored for collaborative environments, including WebSocket message authentication, debug modes, and flexible connection strategies.

Set up the provider

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,
  })
}, [])

Note for On-Premises Customers

If you are hosting your collaboration environment on-premises, replace the appId parameter with baseUrl in your provider configuration to connect to your server.

Configure the collaboration provider

Tiptap Collaboration's provider offers a couple of settings for custom configurations. Review the tables for all parameters, practical use cases, and key concepts like "awareness".

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

Optimize reconnection timings

The provider’s reconnection settings are preset for optimal performance in production settings. If you need to tweak these settings for specific scenarios you can do so with our delay configurations.

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

Setting	Description	Default Value
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