Collaborative editing with Yjs

Collaborative editing with Yjs · Strata Sync


flowchart TB
    subgraph Client A
        EA[Editor] --> YA[Y.Doc]
        YA --> WA[WebSocket]
    end

    subgraph Client B
        EB[Editor] --> YB[Y.Doc]
        YB --> WB[WebSocket]
    end

    subgraph Server
        WA --> SS[Sync Server]
        WB --> SS
        SS --> Redis[(Redis)]
        SS --> PubSub[PubSub]
        PubSub --> SS
        SS --> DB[(Database)]
    end


import { YjsDocumentManager } from "@stratasync/y-doc";

// The transport adapter provides the WebSocket connection
const yjsTransport = transport.getYjsTransport();

const documentManager = new YjsDocumentManager({
  transport: yjsTransport,
});


import type { DocumentKey } from "@stratasync/y-doc";

const docKey: DocumentKey = {
  entityType: "Task",
  entityId: taskId,
  fieldName: "description",
};

// Get or create a Y.Doc for a specific task's description
const doc = documentManager.getDocument(docKey);

// Access the shared text type
const yText = doc.getText("content");


// Connect to start receiving/sending updates
documentManager.connect(docKey);

// Check connection state
const state = documentManager.getConnectionState(docKey);
// "disconnected" | "connecting" | "syncing" | "connected"

// Disconnect when done
documentManager.disconnect(docKey);


"use client";

import { useYjsDocument } from "@stratasync/react";

export function CollaborativeEditor({ taskId }: { taskId: string }) {
  const { doc, connectionState, content } = useYjsDocument({
    entityType: "Task",
    entityId: taskId,
    fieldName: "description",
  });

  if (connectionState === "connecting") {
    return <p>Connecting to editing session...</p>;
  }

  if (!doc) {
    return <p>Loading document...</p>;
  }

  // `content` is a reactive string derived from doc.getText("content")
  // `doc` is the raw Y.Doc for editor binding
  return (
    <div>
      <p>Status: {connectionState}</p>
      <Editor doc={doc} />
    </div>
  );
}


"use client";

import { useYjsPresence } from "@stratasync/react";

export function PresenceBar({ taskId }: { taskId: string }) {
  const { startViewing, stopViewing, isViewing, isEditing } = useYjsPresence({
    entityType: "Task",
    entityId: taskId,
    fieldName: "description",
  });

  return (
    <div className="flex gap-2">
      <div className="text-sm">Viewing: {isViewing ? "Yes" : "No"}</div>
      <div className="text-sm">Editing: {isEditing ? "Yes" : "No"}</div>
    </div>
  );
}


const { startViewing, stopViewing, focus, blur, isViewing, isEditing } =
  useYjsPresence({
    entityType: "Task",
    entityId: taskId,
    fieldName: "description",
  });

// Start viewing when you navigate to the document
startViewing();

// Signal editing when you focus an input
focus(); // Automatically calls startViewing() if not already viewing

// Signal blur when you leave the input
blur();

// Stop viewing when you navigate away
stopViewing();


stateDiagram-v2
    [*] --> NoSession: Document opened
    NoSession --> LiveSession: >= 2 viewers AND >= 1 editor
    LiveSession --> GracePeriod: < 2 viewers OR 0 editors
    GracePeriod --> NoSession: Grace period expires (15-30s)
    GracePeriod --> LiveSession: Conditions met again
    LiveSession --> [*]: All users leave


"use client";

import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";
import Collaboration from "@tiptap/extension-collaboration";
import CollaborationCursor from "@tiptap/extension-collaboration-cursor";
import { useYjsDocument } from "@stratasync/react";

export function TiptapEditor({ taskId }: { taskId: string }) {
  const { doc, connectionState, participants } = useYjsDocument({
    entityType: "Task",
    entityId: taskId,
    fieldName: "description",
  });

  const editor = useEditor(
    {
      extensions: [
        StarterKit.configure({ history: false }),
        Collaboration.configure({ document: doc ?? undefined }),
        CollaborationCursor.configure({
          provider: null, // Strata Sync handles transport
          user: { name: "Current User", color: "#3b82f6" },
        }),
      ],
    },
    [doc]
  );

  if (connectionState === "connecting" || !doc) {
    return <p>Connecting...</p>;
  }

  return (
    <div>
      <div className="flex gap-1 mb-2">
        {participants.map((p) => (
          <span
            key={p.userId}
            className="text-xs px-2 py-1 rounded bg-blue-100"
          >
            {p.userId} {p.isEditing && "(editing)"}
          </span>
        ))}
      </div>
      <EditorContent editor={editor} />
    </div>
  );
}

Collaborative editing with Yjs

Architecture overview

Setting up YjsDocumentManager

Getting a document

Connection management

Using the useYjsDocument hook

Presence tracking with useYjsPresence

Managing presence state

Session lifecycle

Integration with rich-text editors

Tiptap

ProseMirror (direct)

Offline collaboration