Integrate the Collaboration provider

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

Providers handle the complexities of real-time data exchange, including conflict resolution, network reliability, and user presence awareness.

The TiptapCollabProvider adds advanced features tailored for collaborative environments, such as WebSocket message authentication, debug modes, and flexible connection strategies.

Set up the provider

First, install the provider package in your project using:

Set up private registry

Note that you need to follow the instructions here to set up access to the private registry.

npm install @tiptap-pro/provider

For a basic setup, connect to the Collaboration backend by specifying the document's name, your app's ID (for cloud setups), or the base URL (for on-premises), along with your JWT.

Depending on your framework, register a callback to the Collaboration backend, such as useEffect() in React or onMounted() in Vue.js.

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

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

The Tiptap Collaboration provider offers several settings for custom configurations. Review the tables below for all parameters, practical use cases, and key concepts like "awareness".

Setting	Default Value	Description
`appId`	`''` (empty)	App ID for Collaboration Cloud setups
`baseUrl`	`''` (empty)	URL for connecting to on-premises servers. Used as an alternative to `appId` for on-prem setups
`shardKey`	`''` (empty)	Only use this if you use Tiptap Collab HA. Usually this would then be set to the document name, or a team id
`name`	`''` (empty)	The document's name
`token`	`''` (empty)	Authentication token for secure connections. Supports strings, functions, and Promises
`document`	`new Y.Doc()`	The Yjs document instance. Defaults to a new document if none is provided
`user`	`null`	User ID or name for attributing changes to the document.
`forceSyncInterval`	`false`	Forces server sync at regular intervals, in milliseconds

Optimize reconnection timings

The provider’s reconnection settings are preset for optimal performance in production settings. If you need to adjust 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.

Note that these settings can only be configured when creating the TiptapCollabProviderWebsocket instance separately. You'll then need to pass it to the TiptapCollabProvider (as websocketProvider).

Setting	Default Value	Description
`delay`	`1000`	Base delay between reconnection attempts, in milliseconds
`factor`	`2`	Multiplier applied to the delay, increasing it exponentially after each attempt
`initialDelay`	`0`	Time in milliseconds before the first reconnection attempt
`maxAttempts`	`0`	Maximum number of reconnection attempts. `0` means unlimited attempts
`jitter`	`true`	Adds variability to the delay by randomly selecting a value between `minDelay` and the calculated delay for each attempt
`minDelay`	`1000`	Minimum delay when jitter is enabled. Has no effect if jitter is disabled
`maxDelay`	`30000`	Maximum delay allowed between reconnection attempts. Set to `0` to allow the delay to increase indefinitely using exponential backoff (`factor`).
`timeout`	`0`	Time limit, in milliseconds, for each reconnection attempt before stopping
`messageReconnectTimeout`	`30000`	Time in milliseconds to wait for a server message before terminating the connection. If no message is received, the connection is closed automatically

Unsynced changes

The provider maintains an integer that keeps track of the number of unsynced changes. Whenever the server receives a change, it acknowledges it, and the provider decrements the counter.

You should monitor this counter and inform the user when their changes are not yet synced: either before they leave the page or after a certain timeout or number of unsynced changes.

A "change" may be a single character, a single node, or a whole document, depending on your custom use-case, so in general the counter should be at 0 or slightly above, but only for a short period of time (essentially the latency of the connection).

You can get the current value of the counter by accessing TiptapCollabProvider.unsyncedChanges, or by subscribing to the unsyncedChanges event.

TiptapCollabProvider.on('unsyncedChanges', n => console.log(`${n.number} unsynced changes`))

Rate limits

To maintain system integrity and protect from misconfigured clients, our infrastructure—including the management API and websocket connections through the TiptapCollabProvider—is subject to rate limits.

Default rate limits (per source IP):

Requests: 100
Time window: 5 seconds
Burst capacity: Up to 200 requests

If you encounter these limits under normal operation, please email us.

PreviouslyAuthenticate

Next upEvents