---
title: Collaboration
description: How GoTipe keeps one document in sync between editors with its own CRDT, what is shared and what each client keeps.
packages: ["@gotipe/collaboration", "@gotipe/core", "@gotipe/wasm"]
license: MIT
---

Several people can edit one document at the same time. Each editor holds a replica of
GoTipe's own CRDT, `gotipe-crdt`, which is written in Rust and runs in the browser as
WebAssembly. Replicas exchange operations instead of document copies and reach the same
content whatever order the operations arrive in. `@gotipe/collaboration` carries the
operations to GoTipe Cloud over a WebSocket and shows who else is in the document.

```demo
collaboration
```

## How it works

- Every character and every block has a stable identity. An operation names the
  identities it changes, never a numeric offset, so a concurrent edit elsewhere does not
  move it.
- A deleted character stays behind as a tombstone, so an insertion next to it still finds
  its place when the deletion arrives first.
- An operation ID is a Lamport counter plus the `peerId` of the replica that made it. A
  repeated operation changes nothing. A different operation under an existing ID fails the
  whole update, and nothing from that update is applied.
- An update is a set of operations. Updates are replay-safe: you can apply one more than
  once and in any order. The full state adds the baseline document to every operation; an
  edit travels as its new operations only.
- Marks keep the order they were applied in, on every replica: `italic` then `bold` is the
  same JSON and the same HTML nesting for everyone, and undo restores it.
- All replicas start from the same baseline. A replica that already has operations rejects
  a full state built on a different baseline. Replacing the content over REST starts a new
  baseline, and every open editor must load the document again (see
  [When the document is replaced](/docs/collaboration/provider#when-the-document-is-replaced)).
- Undo and redo stay per replica: undo reverts your own operations and keeps everyone
  else's. Turning collaboration on clears the undo history.

## What is shared

Shared through updates:

- Blocks, text, marks and attributes, including nesting, moves, splits and merges.
- Images and files as references in their attributes (`src` of an image, `url` of a file).
  The file itself stays where your [host](/docs/concepts/host) saved it, so every client
  must be able to load it.

Shared through awareness, checked and relayed by the server, never stored:

- Each peer's name, color, avatar, caret, and a selection inside one block.

Not shared, each client keeps its own:

- Undo history, focus, scroll position and read-only state.
- Comments, suggestions and versions. Their managers keep records in memory; your app
  stores and shares them (see [Comments](/docs/review/comments)).
- AI results: proofreading suggestions, review comments and ghost text.
- Decorations, including the review layer of `PageEditor`.

## Requirements

- **The WASM engine.** Create the editor with `engine: "wasm"`. The JS engine has no CRDT,
  and `enableCollaboration()` throws a `GoTipeError` with the code
  `COLLABORATION_UNAVAILABLE`. The default `engine: "auto"` falls back to JS when WASM
  fails to load; `"wasm"` fails with `WASM_INIT_FAILED` instead. See
  [Engines](/docs/getting-started/engines).
- **`@gotipe/wasm`**, an optional peer of `@gotipe/core`, and a CSP that allows WebAssembly.
- **One baseline.** Every replica starts from the same document with the same block IDs.

`PageEditor` always runs on the JS engine, so it cannot join a CRDT session. Use
`BlockEditor` or a headless editor. `PageEditor` can show cursors that your app supplies in
its [review layer](/docs/review/model-edits).

## Install

```sh
npm install @gotipe/core @gotipe/wasm @gotipe/collaboration
```

## Connect to GoTipe Cloud

Load the document over REST, create the editor from its baseline, then connect a provider.
`connect()` replays the stored updates, so connect before you mount the editor and nobody
types into an outdated replica.

```ts title="open-document.ts"
import { CollaborationProvider, type CollaborationState } from "@gotipe/collaboration";
import { createEditor } from "@gotipe/core";
import { FullPreset } from "@gotipe/core/presets";

export async function openDocument(options: {
  apiUrl: string; // https://api.example.com
  wsUrl: string; // wss://sync.example.com/sync
  documentId: string;
  getToken: () => Promise<string>;
  element: HTMLElement;
}) {
  const response = await fetch(
    `${options.apiUrl}/v1/documents/${encodeURIComponent(options.documentId)}`,
    { headers: { Authorization: `Bearer ${await options.getToken()}` } },
  );
  if (!response.ok) throw new Error(`Document load failed: ${response.status}`);
  const initialState: CollaborationState = (await response.json()).collaboration_state;

  const editor = await createEditor({
    engine: "wasm",
    content: initialState.baseline,
    extensions: [FullPreset],
  });
  const provider = new CollaborationProvider({
    documentId: options.documentId,
    wsUrl: options.wsUrl,
    initialState,
    token: options.getToken,
    user: { name: "Alice", color: "#3264ab" },
    onError: (error) => console.warn(error.message),
  });
  provider.connect(editor);
  editor.mount(options.element);
  return { editor, provider };
}
```

Call `provider.destroy()` and `editor.destroy()` when the view closes.
[Provider](/docs/collaboration/provider) lists every option and event.

## Architecture with GoTipe Cloud

1. **Load.** `GET /v1/documents/{id}` returns the rendered `content` and
   `collaboration_state: { baseline, updates, generation }`. Rendered content has no CRDT
   identities, so it cannot serve as a baseline. `generation` is Cloud's name for this
   baseline.
2. **Replay.** You create the editor from `baseline`; the provider applies every stored
   update before input.
3. **Connect.** The provider opens a WebSocket to the sync endpoint (`/sync`, port 8081 by
   default) with the subprotocol `gotipe.v2` and the `generation`. Cloud checks the token,
   the `documents:write` scope and editor access before the upgrade.
4. **Handshake.** Cloud refuses a generation the document no longer has; otherwise it
   sends the current state. The provider merges it, works out what the server lacks and
   reports `connected`.
5. **Edit.** Local changes are sent as their operations alone, the ones the server has not
   confirmed, in frames of at most 512 KiB however large the document is, and only whole
   transactions; a larger transaction goes in parts that Cloud saves together. Cloud
   validates a frame, writes it to PostgreSQL, confirms it with an ACK and forwards it to
   the other peers of the document.
6. **Read.** REST reads and exports run the baseline plus every stored update through the
   same Rust engine. Cloud merges a document's stored updates into one record as they
   accumulate.

Frames are binary: one type byte followed by a UTF-8 JSON payload.
[Realtime](/docs/cloud/realtime) describes each frame.

## Your own transport

`CollaborationProvider` speaks the GoTipe Cloud protocol. For any other transport, use the
editor's collaboration methods directly:

| Method | Description |
| --- | --- |
| `enableCollaboration(peerId)` | Starts a replica at the current document. The peer ID cannot change afterwards. |
| `getCollaborationUpdate()` | Returns the full state, the baseline and every operation, as UTF-8 JSON bytes. Reading it does not drain it. |
| `getCollaborationUpdate({ after, maxBytes? })` | Returns only this replica's operations after the Lamport clock `after`, oldest first, without the baseline. `remaining` in the result counts the later ones that `maxBytes` left out. |
| `getCollaborationUpdate({ missingFrom })` | Takes a peer's full state and returns the operations it lacks, except this replica's own after `acknowledged`, the newest of them in that state. |
| `receiveCollaborationUpdate(bytes)` | Merges an update atomically. Emits `update`, never `transaction`. |

A transport that confirms what it delivered can send `{ after }` updates: remember the
clock of the last operation the other side confirmed and ask for the operations after it.
Operations of one replica are confirmed in order, so that one number is enough. Without
confirmations, send the full state: it is larger and always safe.

This example keeps the tabs of one browser in sync with `BroadcastChannel`. Every tab must
create its editor from the same baseline.

```ts title="tab-sync.ts"
import { type GoTipeEditor, createId } from "@gotipe/core";

export function syncTabs(editor: GoTipeEditor, documentId: string): () => void {
  const channel = new BroadcastChannel(`gotipe:${documentId}`);
  let receiving = false;
  const publish = () => channel.postMessage(editor.getCollaborationUpdate());
  editor.enableCollaboration(createId());
  const stop = editor.on("update", () => {
    // Do not send back an update that just arrived.
    if (!receiving) publish();
  });
  channel.onmessage = (event: MessageEvent<Uint8Array | "sync">) => {
    if (event.data === "sync") return publish();
    receiving = true;
    try {
      editor.receiveCollaborationUpdate(event.data);
    } finally {
      receiving = false;
    }
  };
  channel.postMessage("sync"); // ask the open tabs for their state
  return () => {
    stop();
    channel.close();
  };
}
```

## Limitations

- Collaboration needs the WASM engine. `PageEditor` and editors created from
  `@gotipe/core/js` cannot join a session.
- GoTipe Cloud accepts sync connections only from users with editor access. Viewers can
  read the document over REST but cannot follow edits live.
- Comments, suggestions and versions are not part of the replicated document.
- An edit that arrives during IME composition is not merged with the composed text; the
  editor reports `COMPOSITION_CONFLICT`. See
  [Offline and conflicts](/docs/collaboration/offline).

## Related

- [Collaboration provider](/docs/collaboration/provider): options, tokens, reconnects and cursors.
- [Offline and conflicts](/docs/collaboration/offline): pending edits, local copies, IME.
- [Realtime](/docs/cloud/realtime) and [Authentication](/docs/cloud/auth) in GoTipe Cloud.
- [Engines](/docs/getting-started/engines): WASM and JS.
