How to Add Real-Time Collaboration to a React Editor With Y.js 2026 (Complete Tutorial)

How to Add Real-Time Collaboration to a React Editor With Y.js 2026 (Complete Tutorial)

Adding real-time collaboration to a React editor sounds simple. Then you actually try.

Two users type at the same time. Whose change wins? User A goes offline for 5 minutes. What happens when they reconnect? User B is on a slow 3G connection. Does everyone else stutter? These questions kill weeks of engineering time for teams that pick the wrong architecture.

This tutorial shows exactly how to add real-time collaboration to a React editor using Y.js — the leading CRDT library in 2026. Real working code. Three backend options compared. Honest 1-week and 6-week paths depending on your needs.

Why Real-Time Collaboration Is Hard

Real-time editing hits five specific problems that break naive implementations:

The 3 Paths to React Editor Collaboration

What This Tutorial Covers

• ✅ Y.js fundamentals — CRDTs, awareness, providers
• ✅ 3 working paths — Eddyter (Q3 2026), BlockNote + Liveblocks, custom Lexical + Y.js
• ✅ Backend options compared — Liveblocks, Hocuspocus, y-websocket, PartyKit
• ✅ Complete working code — copy-paste ready
• ✅ Cursor tracking + presence — see who's editing what
• ✅ Offline support — IndexedDB persistence
• ✅ Real 2026 pricing — Liveblocks vs self-hosted
• ✅ 7 common pitfalls — cursor jumping, memory leaks, echo loops, more

If you already know you want the code, jump to Path 2: BlockNote + Liveblocks or Path 3: Custom Lexical + Y.js.

🎥 See a modern editor foundation: What is Eddyter? Why Developers Are Switching in 2026

The Short Answer

Waiting for Eddyter Q3 2026 RTC launch: Pick Eddyter (BlockNote + Liveblocks bridge in the interim). When Eddyter native RTC launches Q3 2026, migration is trivial. $12-$59/mo flat pricing.

Need RTC in production today (Notion-style): Pick BlockNote + Liveblocks. 1 hour setup. React-only. $99/mo Liveblocks.

Need RTC in production today (traditional editor UX): Pick Lexical + Y.js + Liveblocks or custom backend. 1-2 weeks setup with Liveblocks. 4-6 weeks with self-hosted backend.

Full architectural control: Pick Lexical + Y.js + Hocuspocus (self-hosted). 4-6 weeks setup. Free MIT + backend hosting costs.

Understanding Y.js in 5 Minutes

Y.js is a CRDT library — Conflict-Free Replicated Data Type. It solves the "who wins when two users edit the same thing" problem mathematically.

CRDTs vs Operational Transform

Two approaches solve concurrent editing:

Operational Transform (OT): Google Docs' original approach. Rewrites concurrent operations based on other users' actions. Requires a central authority to sequence operations. Complex to implement correctly.

CRDTs (Y.js): Mathematically commutative operations. Any operation order produces the same document. No central authority needed. Simpler mental model.

For 2026, CRDT is the recommended architecture. Y.js is the dominant CRDT implementation.

Core Y.js Concepts

Y.Doc — The document itself. Contains shared data types.

javascript

1
2
import * as Y from 'yjs';
const ydoc = new Y.Doc();

Shared Types — Y.Text, Y.Array, Y.Map. Data structures that sync automatically.

javascript

1
2
const ytext = ydoc.getText('content');
ytext.insert(0, 'Hello world');

Providers — Backends that sync Y.Docs between users.

javascript

1
2
3
4
5
6
import { WebsocketProvider } from 'y-websocket';
const provider = new WebsocketProvider(
  'wss://your-backend.com',
  'room-name',
  ydoc
);

Awareness — Broadcasts user cursors, selections, and presence.

javascript

1
2
3
4
provider.awareness.setLocalStateField('user', {
  name: 'Nimish',
  color: '#c8f751',
});

That's the entire Y.js mental model. Everything else builds on these four concepts.

For broader editor architecture context, see How WYSIWYG Editors Work in 2026: A Developer's Deep Dive and Best Real-Time Collaborative Rich Text Editor for React 2026 (7 Tested).

Y.js Backend Options in 2026

Before writing code, pick a backend. Four options dominate in 2026:

The pattern: Liveblocks wins on developer experience. Hocuspocus wins on cost at scale. y-websocket wins for prototypes. PartyKit wins for Vercel + Cloudflare edge deployments.

<a id="eddyter-path"></a>

Path 1: Wait for Eddyter Native RTC (Q3 2026)

Eddyter's native real-time collaboration launches Q3 2026 with CRDT foundation. When it ships, migration from any Y.js-based setup will be trivial — same underlying CRDT format means data compatibility.

Recommended Interim Approach

While waiting for Eddyter native RTC, deploy Eddyter without collaboration for solo editing use cases. When RTC launches Q3 2026, enable it with a single prop change.

jsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
"use client";
import {
  ConfigurableEditorWithAuth,
  EditorProvider
} from 'eddyter';
import 'eddyter/style.css';
export default function Editor() {
  const apiKey = process.env.NEXT_PUBLIC_EDDYTER_API_KEY;
  return (
    <EditorProvider>
      <ConfigurableEditorWithAuth
        apiKey={apiKey}
        onChange={(html) => saveToDatabase(html)}
        // Post Q3 2026: add these props
        // collaboration={{ room: 'room-name', user: currentUser }}
      />
    </EditorProvider>
  );
}

When Path 1 fits:

• ✅ Solo editing use cases where RTC is a "nice to have" not "must have"
• ✅ You can wait until Q3 2026 for native RTC
• ✅ You value predictable flat pricing over separate Liveblocks subscription
• ✅ You want zero infrastructure to manage

When Path 1 doesn't fit:

• ❌ You need RTC live in production before Q3 2026
• ❌ Your product's core value is multi-user collaboration (use Path 2 or 3)

For deeper Eddyter setup, see How to Add a Rich Text Editor in Next.js 2026 (10-Min Guide) and Best Rich Text Editor for React 2026.

🎥 See Eddyter integration: Integrate Eddyter in 30 Minutes with Cursor, Claude, Lovable

<a id="blocknote-path"></a>

Path 2: BlockNote + Liveblocks (1 Hour Setup)

For teams shipping Notion-style RTC today, BlockNote + Liveblocks is the fastest path. Free MIT-licensed BlockNote core + $99/mo Liveblocks managed backend.

Full Working Setup

Step 1: Install dependencies

bash

1
2
npm install @blocknote/core @blocknote/react @blocknote/mantine
npm install @liveblocks/react @liveblocks/yjs y-protocols yjs

Step 2: Get Liveblocks API keys

Sign up at liveblocks.io. Copy your public and secret keys. Add to .env.local:

bash

1
2
NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY=pk_your_public_key
LIVEBLOCKS_SECRET_KEY=sk_your_secret_key

Step 3: Create Liveblocks provider

Create app/liveblocks-provider.tsx:

jsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
"use client";
import { LiveblocksProvider, RoomProvider } from "@liveblocks/react";
import { ReactNode } from "react";
export default function CollaborativeProvider({
  children,
  roomId,
}: {
  children: ReactNode;
  roomId: string;
}) {
  return (
    <LiveblocksProvider
      publicApiKey={process.env.NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY!}
    >
      <RoomProvider id={roomId} initialPresence={{}}>
        {children}
      </RoomProvider>
    </LiveblocksProvider>
  );
}

Step 4: Create the collaborative editor component

Create components/CollaborativeEditor.tsx:

jsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
"use client";
import { useEffect, useState } from "react";
import { useCreateBlockNote } from "@blocknote/react";
import { BlockNoteView } from "@blocknote/mantine";
import "@blocknote/mantine/style.css";
import { useRoom } from "@liveblocks/react";
import * as Y from "yjs";
import LiveblocksProvider from "@liveblocks/yjs";
export default function CollaborativeEditor({ userName }: { userName: string }) {
  const room = useRoom();
  const [doc, setDoc] = useState<Y.Doc | null>(null);
  const [provider, setProvider] = useState<LiveblocksProvider<any> | null>(null);
  useEffect(() => {
    const ydoc = new Y.Doc();
    const yProvider = new LiveblocksProvider(room, ydoc);
    setDoc(ydoc);
    setProvider(yProvider);
    return () => {
      yProvider.destroy();
      ydoc.destroy();
    };
  }, [room]);
  const editor = useCreateBlockNote({
    collaboration:
      doc && provider
        ? {
            provider,
            fragment: doc.getXmlFragment("document-store"),
            user: {
              name: userName,
              color: "#c8f751",
            },
          }
        : undefined,
  });
  if (!doc || !provider) return <div>Loading collaborative editor...</div>;
  return <BlockNoteView editor={editor} />;
}

Step 5: Use in your app

jsx

1
2
3
4
5
6
7
8
9
10
// app/documents/[id]/page.tsx
import CollaborativeProvider from '@/app/liveblocks-provider';
import CollaborativeEditor from '@/components/CollaborativeEditor';
export default function DocumentPage({ params }: { params: { id: string } }) {
  return (
    <CollaborativeProvider roomId={`document-${params.id}`}>
      <CollaborativeEditor userName="Nimish" />
    </CollaborativeProvider>
  );
}

That's the complete setup. Users see each other's cursors. Edits sync in real-time. Offline changes queue and merge on reconnect.

When Path 2 fits:

• ✅ Notion-style block-based UX matches your product
• ✅ React-only stack (no Vue, Angular, Svelte)
• ✅ Willing to pay $99-$599/mo for managed Liveblocks
• ✅ Want to ship RTC in an hour, not weeks

When Path 2 doesn't fit:

• ❌ You need traditional inline editor UX (not block-based)
• ❌ Multi-framework support required
• ❌ Self-hosting required for compliance

For BlockNote analysis, see BlockNote vs TipTap 2026 and Build a Notion-Style Block Editor in React 2026 (3 Paths).

<a id="lexical-path"></a>

Path 3: Custom Lexical + Y.js (4-6 Weeks, Full Control)

For teams needing traditional editor UX with full architectural control, Lexical + Y.js gives total flexibility. Free MIT license. 4-6 weeks to production quality.

Full Working Setup With Liveblocks

Step 1: Install dependencies

bash

1
2
npm install lexical @lexical/react @lexical/yjs
npm install yjs @liveblocks/react @liveblocks/yjs y-protocols

Step 2: Create the Lexical + Y.js editor

jsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
"use client";
import { useEffect, useState } from 'react';
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
import { CollaborationPlugin } from '@lexical/react/LexicalCollaborationPlugin';
import { useRoom } from '@liveblocks/react';
import * as Y from 'yjs';
import LiveblocksProvider from '@liveblocks/yjs';
function CollaborativeLexicalEditor({ userName }: { userName: string }) {
  const room = useRoom();
  const [provider, setProvider] = useState<LiveblocksProvider<any> | null>(null);
  useEffect(() => {
    const ydoc = new Y.Doc();
    const yProvider = new LiveblocksProvider(room, ydoc);
    setProvider(yProvider);
    return () => {
      yProvider.destroy();
      ydoc.destroy();
    };
  }, [room]);
  if (!provider) return <div>Connecting to collaboration...</div>;
  const editorConfig = {
    namespace: 'CollaborativeEditor',
    onError: (error: Error) => console.error(error),
    editorState: null, // Y.js manages state
    theme: {
      paragraph: 'editor-paragraph',
      text: {
        bold: 'font-bold',
        italic: 'italic',
      },
    },
  };
  return (
    <LexicalComposer initialConfig={editorConfig}>
      <div className="editor-container">
        <RichTextPlugin
          contentEditable={<ContentEditable className="editor-content" />}
          placeholder={<div className="editor-placeholder">Start writing...</div>}
          ErrorBoundary={LexicalErrorBoundary}
        />
        <HistoryPlugin />
        <CollaborationPlugin
          id="collaborative-doc"
          providerFactory={() => provider}
          shouldBootstrap={true}
          username={userName}
          cursorColor="#c8f751"
        />
      </div>
    </LexicalComposer>
  );
}
export default CollaborativeLexicalEditor;

Step 3: Add cursor tracking with awareness

The CollaborationPlugin handles cursor tracking automatically via Y.js awareness. Each user's cursor appears with their name and color.

Step 4: Add offline persistence with IndexedDB

jsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { IndexeddbPersistence } from 'y-indexeddb';
useEffect(() => {
  const ydoc = new Y.Doc();
  const persistence = new IndexeddbPersistence('document-id', ydoc);
  persistence.on('synced', () => {
    console.log('Local content loaded');
  });
  const yProvider = new LiveblocksProvider(room, ydoc);
  setProvider(yProvider);
  return () => {
    persistence.destroy();
    yProvider.destroy();
    ydoc.destroy();
  };
}, [room]);

Step 5: Self-hosted alternative with Hocuspocus

For teams preferring self-hosted backends, replace Liveblocks with Hocuspocus:

javascript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// server.js
import { Server } from '@hocuspocus/server';
const server = Server.configure({
  port: 1234,
  async onAuthenticate({ token, documentName }) {
    // Validate JWT token
    return { user: { name: 'Nimish' } };
  },
  async onLoadDocument({ documentName }) {
    // Load initial document state from database
  },
  async onStoreDocument({ documentName, document }) {
    // Persist document state to database
  },
});
server.listen();

Then in your React component:

jsx

1
2
3
4
5
6
import { HocuspocusProvider } from '@hocuspocus/provider';
const provider = new HocuspocusProvider({
  url: 'ws://localhost:1234',
  name: 'document-name',
  token: 'user-jwt-token',
});

Self-hosted Hocuspocus costs $20-$200/mo in server hosting vs Liveblocks' $99-$599/mo but requires ops maintenance.

When Path 3 fits:

• ✅ Traditional inline editor UX (not Notion-style blocks)
• ✅ Full architectural control needed
• ✅ 4-6 weeks engineering time available
• ✅ Free MIT license required for commercial use
• ✅ Multi-framework support possible (though this example is React)

When Path 3 doesn't fit:

• ❌ You want to ship in days, not weeks
• ❌ Notion-style UX is a requirement (use Path 2)
• ❌ You don't have Lexical expertise on team

For deeper analysis, see Best Lexical Alternative 2026, How to Migrate From TipTap to Lexical 2026, and How WYSIWYG Editors Work in 2026: A Developer's Deep Dive.

Real Cost Math: 3-Year TCO for React Editor Collaboration

For a typical React SaaS with 1,000 users editing 500 documents monthly, here's what each path actually costs over three years:

Eddyter Q3 2026 saves $1,440-$68,000 over 3 years vs alternatives. For teams that can wait until Q3 2026, waiting delivers the best long-term economics.

For build-vs-buy analysis, see Build vs Buy: Real Cost of Building a Rich Text Editor 2026 and Why Building Your Own Rich Text Editor Is a Startup Killer.

7 Common Y.js Collaboration Pitfalls

Teams adding real-time collaboration consistently hit these issues.

Pitfall 1: Cursor Jumping on Remote Edits

Your cursor jumps when someone else types. Fix: use Y.js awareness with proper cursor tracking that preserves your local position on remote changes.

Pitfall 2: Undo/Redo Undoes Teammates' Work

Ctrl+Z removes changes from other users. Fix: Y.js UndoManager tracks operations per-origin. Only undo your own operations.

Pitfall 3: Memory Leaks on Component Unmount

Not destroying Y.Doc and providers on unmount leaks memory. Fix: Always call provider.destroy() and ydoc.destroy() in useEffect cleanup.

Pitfall 4: Echo Loops Between Editor and Y.js

Editor updates trigger Y.js updates which trigger editor updates. Fix: use origin tags to prevent applying your own operations twice.

Pitfall 5: Offline Changes Lost on Reconnect

Local changes disappear when connection restores. Fix: use IndexedDB persistence layer alongside network provider.

Pitfall 6: Slow Performance With Long Documents

Documents over 10,000 characters slow down. Fix: enable Y.js garbage collection and use virtualization for rendering.

Pitfall 7: Awareness Storms on Frequent Updates

Cursor position broadcasts every keystroke floods the network. Fix: throttle awareness updates to 100-200ms intervals.

Best Path by Use Case

Different RTC use cases call for different paths.

For Notion Clones and Block-Based Products

Pick Path 2 (BlockNote + Liveblocks). Block-based UX matches Notion mental model. 1-hour setup. $99/mo Liveblocks. See Build a Notion-Style Block Editor in React 2026 (3 Paths).

For Traditional Google Docs-Style Editors

Pick Path 3 (Lexical + Y.js + Liveblocks). Traditional inline editing UX with real-time collaboration. 1-2 weeks setup with Liveblocks. See Best Lexical Alternative 2026.

For Enterprise Compliance (SOC 2 / HIPAA Today)

Pick CKEditor 5 Cloud. SOC 2 Type II certified with real-time collaboration built in. See Eddyter vs CKEditor 2026 and Best CKEditor Alternative 2026.

For Self-Hosted Compliance

Pick Path 3 with Hocuspocus. Self-hosted Y.js backend. Full data sovereignty. 4-6 weeks setup.

For AI Writing Tools With Collaboration

Pick Eddyter (post Q3 2026) or Lexical + Y.js + custom AI. Both support AI streaming + collaboration. See Best Rich Text Editor for AI Writing Assistants 2026 and Best Rich Text Editors for AI Apps 2026.

For Real-Time Code Editors

Pick Monaco/CodeMirror + Y.js. Not covered in this tutorial but same Y.js patterns apply. Rich text patterns above translate directly.

For Prototypes and MVPs

Pick Path 2 (BlockNote + Liveblocks). Fastest path to working RTC. Free Liveblocks tier available for prototyping.

For framework-specific guidance, see:

• Best Rich Text Editor for React 2026
• Best Rich Text Editor for Next.js App Router 2026
• Best Rich Text Editor for B2B SaaS Apps 2026

Frequently Asked Questions

1. What is Y.js and why should I use it for React editor collaboration?

Y.js is a CRDT library — Conflict-Free Replicated Data Type. It solves the "who wins when two users edit the same thing" problem mathematically. Two users can type simultaneously, work offline, and reconnect — Y.js merges everything deterministically without a central authority. For 2026 React editor collaboration, Y.js is the dominant choice because it's mathematically proven, actively maintained, and integrates cleanly with Lexical, TipTap, BlockNote, ProseMirror, and other modern editor frameworks. Alternatives like Operational Transform (OT) require more complex backend infrastructure.

2. How do I add real-time collaboration to a React editor with Y.js?

Three paths depending on your needs. Fast path (1 hour): BlockNote + Liveblocks for Notion-style products. Complete working code shown in the BlockNote + Liveblocks section above. Traditional editor path (1-2 weeks): Lexical + Y.js + Liveblocks. Working code in the Lexical + Y.js section. Full control path (4-6 weeks): Lexical + Y.js + self-hosted Hocuspocus. All three paths use Y.js as the CRDT foundation. Choose based on UX requirements (block-based vs traditional), time budget (hours vs weeks), and hosting preference (managed vs self-hosted).

3. Which Y.js backend should I use — Liveblocks, Hocuspocus, or y-websocket?

Depends on team preferences. Liveblocks ($99-$599/mo) wins on developer experience — managed infrastructure, real-time cursor tracking, presence, comments all included. Best for teams shipping fast without ops burden. Hocuspocus (self-hosted, $20-$200/mo server costs) wins on cost at scale and full control — best for teams with DevOps expertise and long-term cost concerns. y-websocket (simplest self-hosted) wins for prototypes and MVPs — minimal setup but lacks Hocuspocus's advanced features. PartyKit ($20/mo Pro) wins for Vercel + Cloudflare edge deployments. For most React teams shipping today, Liveblocks delivers the best developer experience.

4. Can I add Y.js collaboration to my existing React editor?

Yes, if your editor uses Lexical, TipTap, BlockNote, or ProseMirror. These editors have first-class Y.js integrations. Add @lexical/yjs (Lexical), @tiptap/extension-collaboration (TipTap), or use BlockNote's built-in collaboration prop. For editors without Y.js support (TinyMCE, CKEditor 5 without their commercial collaboration add-on, Quill, Slate), migration to a Y.js-compatible editor is required first. Working migration paths in How to Migrate From TipTap to Lexical 2026 and How to Migrate From TinyMCE to a Modern Editor 2026.

5. How much does real-time collaboration cost in 2026?

Depends on approach. Managed backends: Liveblocks Starter $99/mo (100 monthly active users), Liveblocks Business $599/mo (5,000 MAU). PartyKit Pro $20/mo. Self-hosted: Hocuspocus + server hosting $20-$200/mo depending on scale. y-websocket + server hosting $20-$100/mo. Full custom builds add $60,000-$100,000+ in initial engineering plus ongoing maintenance. Eddyter's Q3 2026 native RTC will include collaboration in the base subscription ($12-$59/mo) with no separate backend costs — best long-term economics for teams that can wait until Q3 2026.

6. Should I wait for Eddyter Q3 2026 native RTC or ship with Y.js today?

Depends on urgency. If collaboration is a "nice to have" that can wait 3-6 months, waiting for Eddyter Q3 2026 native RTC delivers best long-term economics — collaboration included in $12-$59/mo base subscription with no separate Liveblocks bill. If collaboration is a "must have" for launch or early revenue, ship with BlockNote + Liveblocks (1 hour) or Lexical + Y.js (1-2 weeks). Both approaches use Y.js as the CRDT foundation, meaning data migration to Eddyter native RTC when it launches will be trivial — same underlying CRDT format ensures compatibility.

Ready to Add Real-Time Collaboration to Your React Editor?

Stop engineering conflict resolution, presence tracking, and offline sync from scratch. Three paths to production RTC in your React app — waiting for Eddyter Q3 2026 native RTC ($12-$59/mo flat), BlockNote + Liveblocks (1-hour setup, $99/mo), or Lexical + Y.js custom build (4-6 weeks, full control).

👉 Try Eddyter free at eddyter.com
📚 Read the docs
💰 See pricing
🎥 Watch the intro video | Watch the 30-min integration guide