Collaboration

Charts and diagrams are nodes like any other, so Tiptap Collaboration shares them without extra setup. One rule applies: every client that opens the shared document registers Diagrams.

Where to register Diagrams

Register Diagrams everywhere the shared document is opened: in each editor, in a read-only viewer and in an agent.

A collaboration server has no editor. Where it turns the shared document into Tiptap JSON or back, it uses a schema built with Diagrams, as in A client that shows nothing.

A client you missed deletes every chart and diagram from the shared document, unless it sets enableContentCheck: true. See A client without Diagrams.

Two people changing one chart

A chart stores its data, its Chart Spec (its settings) and its Renderer as separate attributes, and the shared document merges each attribute on its own:

  • Changes to different attributes at the same time are both kept, such as a title and a cell.
  • Changes to the data at the same time keep only one of them, the same on every client, even in different cells, because the data is one attribute.
  • Undo takes back only your own change, also after somebody else changed the chart.

A diagram's source is one attribute too, so the same applies.

A client without Diagrams

A client whose schema, the nodes its editor knows, has no chart or flowDiagram node cannot build them. Nor can one that sets chart: false or flowDiagram: false. What happens then depends on the editor option enableContentCheck:

enableContentCheckThe shared documentThat client
false (default)Loses the charts or diagrams that client cannot build. The deletion reaches every other clientDeletes them while it loads the document
trueStays as it is. Everybody else keeps their charts and diagramsShows the rest of the document, cannot be edited, sends nothing, and emits contentError

enableContentCheck: true needs @tiptap/extension-collaboration 3.33.0 and @tiptap/y-tiptap 3.2.0 or later. With older versions, the client deletes those charts or diagrams in both cases. Only @tiptap/y-tiptap 3.0.10 and 3.0.11 behave differently: they make the editor read-only and may show an empty or outdated document.

Set enableContentCheck: true on every client that might not register Diagrams, for example an older version of your app. That client stays paused while the document contains charts or diagrams it cannot build. Also set onContentError, because the default handler throws the error. See Invalid schema handling.

A client that shows nothing

A client that draws nothing registers Diagrams with no Renderer. It needs no DOM and no chart library, and it keeps every chart and diagram as it is. renderers: [] is enough, because diagramRenderers, the Renderers for diagrams, is empty by default:

import { getSchema } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Diagrams } from '@tiptap-pro/extension-diagrams'

const extensions = [StarterKit, Diagrams.configure({ renderers: [] })]
const schema = getSchema(extensions)

An editor without a Renderer shows each chart or diagram as not drawable here, or as what unavailable returns. Its data stays untouched.

Turning away a client without Diagrams

If clients you do not control can connect, let the server refuse those that do not declare Diagrams. With Hocuspocus, Tiptap's collaboration server, the client adds a parameter you choose to its connection, and the server checks it before loading the document:

// client
const provider = new HocuspocusProvider({
  url: 'wss://collaboration.example.com?schema=diagram-1',
  name: 'document-id',
})

// server
const server = new Hocuspocus({
  async onConnect({ requestParameters }) {
    if (requestParameters.get('schema') !== 'diagram-1') {
      throw new Error('This document needs the Diagrams extension.')
    }
  },
})

Mixed versions

A newer version of @tiptap-pro/extension-diagrams may store a chart attribute that an older client does not know. The older client keeps that attribute only until it changes the chart, and then the attribute is lost. So update every client before you use a feature that a newer version added.