Tiptap collaboration: connect editors to the same shared document

Consider an original shift-handover note with two authors. One corrects the collection location, while the other adds a handling instruction. Both need to edit the same note without a later whole-document save erasing the other person's contribution. A shared document binding changes how that note is maintained.

Bind the editor to the provider's document

In an existing Tiptap 3 application, use the same Yjs document object for the provider and the editor extension. The following fragment assumes the application's provider has already been configured with its document identity, connection, authentication, and persistence policy:

import StarterKit from '@tiptap/starter-kit';
import Collaboration from '@tiptap/extension-collaboration';

function handoverExtensions(sharedDocument) {
  return [
    StarterKit.configure({ undoRedo: false }),
    Collaboration.configure({
      document: sharedDocument,
      field: 'handover'
    })
  ];
}

Pass the returned array to the real editor's extensions option. sharedDocument is the Yjs document connected by the provider. Creating a second unrelated document for the editor would leave it outside the provider's synchronized state.

The field names a Yjs fragment inside that document. Both clients editing the handover must use the same fragment name. Different fields can intentionally hold different editor areas, such as a title and a body. A match at the server document level is therefore insufficient if the clients bind to different fields.

Keep package versions compatible with the installed Tiptap release. StarterKit configuration documents the current undoRedo key; older examples may use a different history option.

Trace the identity before debugging a missing edit

For the fictional handover, record the intended backend document identifier and the fragment handover. Open that note in two authorized development clients. If an edit fails to appear, inspect the connection and document mapping before rewriting editor content:

The collaboration overview describes Yjs synchronization and document management. Choose its installation and authentication instructions for the backend you actually use. The short extension fragment above supplies no server or credentials.

Initialize the note once through a deliberate process

Keep an existing shared note as the authoritative starting point when another participant joins. Replacing its content from a stale HTML response on every mount can reintroduce old wording or create duplicate content. Define how the application creates a new shared note, and distinguish that operation from opening one that already exists.

For a migration, retain the source note, import it through the supported backend workflow, then open the resulting shared document in both clients. Check that the initial paragraph appears once. Treat repeated paragraphs as an initialization defect to investigate before allowing ordinary editing.

An HTML or JSON reading snapshot is useful for rendering and export, but the synchronization layer also has its own state and persistence requirements. Document which representation the backend maintains and how it restores it. A local getHTML() capture cannot establish that the collaboration service stored the corresponding document.

Check merged text and local undo separately

Start the handover fixture with “Collect the cases at the west desk.” In client A, change “west desk” to “loading entrance.” After both clients show that correction, client B adds a new paragraph: “Keep the temperature logger with the cases.”

Read the combined result in both clients. Then use Undo in client A and inspect which local operation it reverses. Collaboration's history is designed for collaborative editing, where one author's undo should not simply rewind everyone else's work. Repeat with the actual commands and plugins in your application, and confirm client B's separate instruction remains correct.

Close both clients and reopen the note through the real application. The collection location and handling instruction must survive the backend round trip. Also verify that a user without access cannot open the document. Synchronization is not evidence of authorization, and a hidden toolbar does not enforce server access.

Roll out schema changes with connected authors in mind

Tiptap's collaboration documentation warns that clients with different schemas can remove content they do not recognize. Before enabling a new node type, plan how older open clients will update or stop editing. Test that policy with an older client still connected to a development note containing the new structure.

The Vue Tiptap integration explains ordinary document capture and replacement. Keep its local editing example separate from this shared-document model. Finish the collaboration setup by reopening the merged handover from storage and having both authors confirm the actual collection instruction.