Tiptap Collab

Tiptap Collab is our hosted solution of Hocuspocus for those who don't want to maintain their own deployment.

Pro Feature

To get started, you need a Tiptap Pro account (sign up / login here).

Cloud Dashboard

Note that you need @hocuspocus/provider ~v2.0.0

Getting started

import { TiptapCollabProvider } from '@hocuspocus/provider'

const provider = new TiptapCollabProvider({
  appId: 'your_app_id', // get this at collab.tiptap.dev
  name: 'your_document_name', // e.g. a uuid uuidv4();
  token: 'your_JWT', // see "Authentication" below

Upgrade from self-hosted deployments

If you are upgrading from a self-hosted deployment, on the frontend you just need to replace HocuspocusProvider with the new TiptapCollabProvider. The API is the same, it's just a wrapper that handles hostnames / auth.


replit / Sandbox: Fully functional prototype

Cloud Documents

We have created a simple client / server setup using replit, which you can review and fork here:

Github or Replit (Live-Demo)

The example load multiple documents over the same websocket (multiplexing), and shows how to realize per-document authentication using JWT.


Authentication is done using JWT. You can see your secret in the admin interface and use it to generate tokens for your clients. If you want to generate a JWT and add some attributes for testing, you can use http://jwtbuilder.jamiekurtz.com/ . You can leave all fields default, just replace the "key" with the secret from your settings.

In Node.js, you can generate a JWT like this:

import jsonwebtoken from 'jsonwebtoken'

const data = {
  // use this list to limit the number of documents that can be accessed by this client.
  // empty array means no access at all
  // not sending this property means access to all documents
  allowedDocumentNames: ['document-1', 'document-2']

const jwt = jsonwebtoken.sign(data, 'your_secret')
// this JWT should be sent in the `token` field of the provider. Never expose 'your_secret' to a frontend!

Getting the JSON document

If you want to access the JSON representation (we're currently exporting the default fragment of the YDoc), you can add a webhook in the admin interface. We are calling it when storing to our database, so it's debounced by 2 seconds (max 10 seconds).

All requests contain a header X-Hocuspocus-Signature-256 which signs the entire message using 'your_secret' (find it in the settings). The payload looks like this:

  "appName": '', // name of your app
  "name": '', // name of the document
  "time": // current time as ISOString (new Date()).toISOString())
  "tiptapData": {}, // JSON output from Tiptap (see https://tiptap.dev/guide/output#option-1-json): TiptapTransformer.fromYdoc()
  "ydocState"?: {}, // optionally contains the entire yDoc as base64. Contact us to enable this property!
  "clientsCount": 100 // number of currently connected clients


Cloud Documents

Cloud Settings

Need anything else?

Contact us on Discord or send an email to humans@tiptap.dev.