Rork Max × Liveblocks / Yjs: Real-Time Collaborative App Development

# Install Yjs and the Liveblocks SDK
npx expo install yjs @liveblocks/client @liveblocks/react
 
# Liveblocks-compatible Yjs provider
npx expo install @liveblocks/yjs

EXPO_PUBLIC_LIVEBLOCKS_PUBLIC_KEY=pk_live_YOUR_PUBLIC_KEY_HERE

import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";
 
const client = createClient({
  publicApiKey: process.env.EXPO_PUBLIC_LIVEBLOCKS_PUBLIC_KEY!,
  // Throttle awareness updates to 100ms
  throttle: 100,
});
 
// Each user's real-time state
type Presence = {
  cursor: { x: number; y: number } | null;
  username: string;
  color: string;
  selectedNodeId: string | null;
};
 
// CRDT-synchronized document state
type Storage = {
  documentTitle: string;
  collaborators: string[];
};
 
type UserMeta = {
  id: string;
  info: {
    name: string;
    avatar?: string;
  };
};
 
type RoomEvent =
  | { type: "SELECTION_CHANGE"; nodeId: string }
  | { type: "COMMENT_ADDED"; commentId: string };
 
export const {
  RoomProvider,
  useRoom,
  useMyPresence,
  useOthers,
  useOther,
  useBroadcastEvent,
  useEventListener,
  useStorage,
  useMutation,
} = createRoomContext<Presence, Storage, UserMeta, RoomEvent>(client);

import { useEffect, useRef, useState } from "react";
import * as Y from "yjs";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import { useRoom } from "../lib/liveblocks";
 
interface UseCollaborativeDocOptions {
  documentId: string;
}
 
export function useCollaborativeDoc({ documentId }: UseCollaborativeDocOptions) {
  const room = useRoom();
  const [isConnected, setIsConnected] = useState(false);
  const [isSynced, setIsSynced] = useState(false);
 
  const ydocRef = useRef<Y.Doc>(new Y.Doc());
  const providerRef = useRef<LiveblocksYjsProvider | null>(null);
 
  useEffect(() => {
    const ydoc = ydocRef.current;
    const provider = new LiveblocksYjsProvider(room, ydoc);
    providerRef.current = provider;
 
    provider.on("sync", (synced: boolean) => {
      setIsSynced(synced);
    });
 
    provider.on("status", ({ status }: { status: string }) => {
      setIsConnected(status === "connected");
    });
 
    return () => {
      provider.destroy();
      providerRef.current = null;
    };
  }, [room]);
 
  const yText = ydocRef.current.getText("content");
  const yMeta = ydocRef.current.getMap("metadata");
 
  return {
    ydoc: ydocRef.current,
    provider: providerRef.current,
    yText,
    yMeta,
    isConnected,
    isSynced,
  };
}

// src/components/CollaboratorAvatars.tsx
import React from "react";
import { View, Text, StyleSheet } from "react-native";
import { useOthers, useMyPresence } from "../lib/liveblocks";
 
const USER_COLORS = [
  "#E57373", "#F06292", "#BA68C8", "#7986CB",
  "#4FC3F7", "#4DB6AC", "#81C784", "#FFD54F",
];
 
function getColorForUser(userId: string): string {
  let hash = 0;
  for (let i = 0; i < userId.length; i++) {
    hash = userId.charCodeAt(i) + ((hash << 5) - hash);
  }
  return USER_COLORS[Math.abs(hash) % USER_COLORS.length];
}
 
export function CollaboratorAvatars() {
  const others = useOthers();
 
  return (
    <View style={styles.container}>
      <View style={[styles.avatar, { backgroundColor: "#4CAF50" }]}>
        <Text style={styles.initial}>You</Text>
      </View>
 
      {others.slice(0, 5).map((other) => (
        <View
          key={other.connectionId}
          style={[
            styles.avatar,
            { backgroundColor: getColorForUser(String(other.connectionId)) },
          ]}
        >
          <Text style={styles.initial}>
            {other.presence.username?.charAt(0).toUpperCase() ?? "?"}
          </Text>
        </View>
      ))}
 
      {others.length > 5 && (
        <View style={[styles.avatar, styles.overflowAvatar]}>
          <Text style={styles.initial}>+{others.length - 5}</Text>
        </View>
      )}
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flexDirection: "row", alignItems: "center", gap: -8 },
  avatar: {
    width: 32,
    height: 32,
    borderRadius: 16,
    justifyContent: "center",
    alignItems: "center",
    borderWidth: 2,
    borderColor: "#FFFFFF",
  },
  overflowAvatar: { backgroundColor: "#9E9E9E" },
  initial: { color: "#FFFFFF", fontSize: 11, fontWeight: "700" },
});

// src/components/CollaborativeTextEditor.tsx
import React, { useEffect, useState, useCallback } from "react";
import {
  TextInput,
  View,
  Text,
  StyleSheet,
  ActivityIndicator,
} from "react-native";
import * as Y from "yjs";
 
interface CollaborativeTextEditorProps {
  yText: Y.Text;
  isConnected: boolean;
  isSynced: boolean;
  placeholder?: string;
}
 
export function CollaborativeTextEditor({
  yText,
  isConnected,
  isSynced,
  placeholder = "Start typing here...",
}: CollaborativeTextEditorProps) {
  const [content, setContent] = useState("");
 
  useEffect(() => {
    const handleChange = (_: Y.YTextEvent[], transaction: Y.Transaction) => {
      if (transaction.local) return;
      setContent(yText.toString());
    };
 
    setContent(yText.toString());
    yText.observe(handleChange);
    return () => yText.unobserve(handleChange);
  }, [yText]);
 
  const handleTextChange = useCallback(
    (newText: string) => {
      const oldText = yText.toString();
 
      // Compute common prefix
      let prefixLen = 0;
      while (
        prefixLen < oldText.length &&
        prefixLen < newText.length &&
        oldText[prefixLen] === newText[prefixLen]
      ) {
        prefixLen++;
      }
 
      // Compute common suffix
      let suffixLen = 0;
      while (
        suffixLen < oldText.length - prefixLen &&
        suffixLen < newText.length - prefixLen &&
        oldText[oldText.length - 1 - suffixLen] ===
          newText[newText.length - 1 - suffixLen]
      ) {
        suffixLen++;
      }
 
      const deleteCount = oldText.length - prefixLen - suffixLen;
      const insertText = newText.slice(prefixLen, newText.length - suffixLen);
 
      // Apply as a single atomic Yjs transaction
      yText.doc?.transact(() => {
        if (deleteCount > 0) yText.delete(prefixLen, deleteCount);
        if (insertText.length > 0) yText.insert(prefixLen, insertText);
      });
 
      setContent(newText);
    },
    [yText]
  );
 
  return (
    <View style={styles.container}>
      <View style={styles.statusBar}>
        {!isConnected ? (
          <View style={styles.row}>
            <View style={[styles.dot, styles.dotOffline]} />
            <Text style={styles.statusText}>Offline — reconnecting...</Text>
          </View>
        ) : !isSynced ? (
          <View style={styles.row}>
            <ActivityIndicator size="small" color="#FF9800" />
            <Text style={styles.statusText}>Syncing...</Text>
          </View>
        ) : (
          <View style={styles.row}>
            <View style={[styles.dot, styles.dotOnline]} />
            <Text style={styles.statusText}>Live sync active</Text>
          </View>
        )}
      </View>
 
      <TextInput
        style={styles.editor}
        multiline
        value={content}
        onChangeText={handleTextChange}
        placeholder={placeholder}
        placeholderTextColor="#9E9E9E"
        textAlignVertical="top"
        scrollEnabled
      />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: "#FFFFFF" },
  statusBar: {
    paddingHorizontal: 16,
    paddingVertical: 8,
    backgroundColor: "#F5F5F5",
    borderBottomWidth: 1,
    borderBottomColor: "#E0E0E0",
  },
  row: { flexDirection: "row", alignItems: "center", gap: 6 },
  dot: { width: 8, height: 8, borderRadius: 4 },
  dotOnline: { backgroundColor: "#4CAF50" },
  dotOffline: { backgroundColor: "#F44336" },
  statusText: { fontSize: 12, color: "#666666" },
  editor: {
    flex: 1,
    padding: 16,
    fontSize: 16,
    lineHeight: 24,
    color: "#212121",
  },
});

// src/app/document/[id].tsx
import React from "react";
import { View, StyleSheet } from "react-native";
import { useLocalSearchParams } from "expo-router";
import { RoomProvider } from "../../lib/liveblocks";
import { CollaborativeDocumentScreen } from "../../components/CollaborativeDocumentScreen";
 
const COLORS = ["#E57373", "#64B5F6", "#81C784", "#FFD54F", "#BA68C8"];
const randomColor = () => COLORS[Math.floor(Math.random() * COLORS.length)];
 
export default function DocumentPage() {
  const { id } = useLocalSearchParams<{ id: string }>();
 
  return (
    <RoomProvider
      id={`document-${id}`}
      initialPresence={{
        cursor: null,
        username: "User", // Replace with auth user's name
        color: randomColor(),
        selectedNodeId: null,
      }}
      initialStorage={{
        documentTitle: "Untitled Document",
        collaborators: [],
      }}
    >
      <View style={styles.container}>
        <CollaborativeDocumentScreen documentId={id} />
      </View>
    </RoomProvider>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: "#FFFFFF" },
});

-- Document table
CREATE TABLE documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL DEFAULT 'Untitled Document',
  owner_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  liveblocks_room_id TEXT UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  is_public BOOLEAN DEFAULT FALSE
);
 
-- Collaborator permissions
CREATE TABLE document_collaborators (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  document_id UUID REFERENCES documents(id) ON DELETE CASCADE,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  permission TEXT CHECK (permission IN ('view', 'edit', 'admin')),
  invited_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(document_id, user_id)
);
 
-- Row Level Security
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY "Owners have full access" ON documents
  FOR ALL USING (auth.uid() = owner_id);
 
CREATE POLICY "Collaborators can view" ON documents
  FOR SELECT USING (
    EXISTS (
      SELECT 1 FROM document_collaborators
      WHERE document_id = id AND user_id = auth.uid()
    )
    OR is_public = TRUE
  );

// src/hooks/useOfflineSync.ts
import { useEffect, useState } from "react";
import NetInfo from "@react-native-community/netinfo";
import AsyncStorage from "@react-native-async-storage/async-storage";
import * as Y from "yjs";
 
const PREFIX = "yjs_doc_";
 
export function useOfflineSync(ydoc: Y.Doc, documentId: string) {
  const [isOnline, setIsOnline] = useState(true);
 
  useEffect(() => {
    const unsub = NetInfo.addEventListener((state) => {
      setIsOnline(state.isConnected ?? false);
    });
    return unsub;
  }, []);
 
  // Persist Yjs state to AsyncStorage (debounced 2s)
  useEffect(() => {
    let timer: ReturnType<typeof setTimeout>;
 
    const save = () => {
      clearTimeout(timer);
      timer = setTimeout(async () => {
        const state = Y.encodeStateAsUpdate(ydoc);
        const base64 = Buffer.from(state).toString("base64");
        await AsyncStorage.setItem(`${PREFIX}${documentId}`, base64);
      }, 2000);
    };
 
    ydoc.on("update", save);
    return () => {
      ydoc.off("update", save);
      clearTimeout(timer);
    };
  }, [ydoc, documentId]);
 
  // Load local state on mount
  useEffect(() => {
    (async () => {
      const base64 = await AsyncStorage.getItem(`${PREFIX}${documentId}`);
      if (base64) {
        const state = Buffer.from(base64, "base64");
        Y.applyUpdate(ydoc, state); // Merges with any remote state
      }
    })();
  }, [ydoc, documentId]);
 
  return { isOnline };
}

// Periodically snapshot the document state to trim the update history
const snapshot = Y.snapshot(ydoc);
const encoded = Y.encodeSnapshot(snapshot);
// Save to Supabase Storage; new clients load from the snapshot

// Bundle many changes into a single WebSocket message
ydoc.transact(() => {
  yText.insert(0, "batched ");
  yText.insert(8, "update");
});

// src/components/CollaborativeCanvas.tsx
import React, { useCallback, useRef } from "react";
import { View, PanResponder, StyleSheet } from "react-native";
import Svg, { Path } from "react-native-svg";
import * as Y from "yjs";
 
interface Shape {
  id: string;
  path: string;   // SVG path data
  color: string;
  author: string;
}
 
interface CollaborativeCanvasProps {
  yShapes: Y.Map<Shape>;
  userColor: string;
  username: string;
}
 
export function CollaborativeCanvas({
  yShapes,
  userColor,
  username,
}: CollaborativeCanvasProps) {
  const currentPathRef = useRef<string[]>([]);
  const shapeIdRef = useRef<string>(
    `${username}-${Date.now()}`
  );
 
  // Convert touch points to SVG path string
  const buildPath = (points: string[]) => points.join(" ");
 
  const panResponder = PanResponder.create({
    onStartShouldSetPanResponder: () => true,
 
    onPanResponderGrant: (evt) => {
      const { locationX, locationY } = evt.nativeEvent;
      shapeIdRef.current = `${username}-${Date.now()}`;
      currentPathRef.current = [`M ${locationX} ${locationY}`];
    },
 
    onPanResponderMove: (evt) => {
      const { locationX, locationY } = evt.nativeEvent;
      currentPathRef.current.push(`L ${locationX} ${locationY}`);
 
      // Broadcast intermediate state so others see the stroke in progress
      yShapes.set(shapeIdRef.current, {
        id: shapeIdRef.current,
        path: buildPath(currentPathRef.current),
        color: userColor,
        author: username,
      });
    },
 
    onPanResponderRelease: () => {
      // Finalize the stroke — it stays in the shared map
      currentPathRef.current = [];
    },
  });
 
  // Render all shapes from shared state
  const shapes = Array.from(yShapes.values());
 
  return (
    <View style={styles.canvas} {...panResponder.panHandlers}>
      <Svg style={StyleSheet.absoluteFill}>
        {shapes.map((shape) => (
          <Path
            key={shape.id}
            d={shape.path}
            stroke={shape.color}
            strokeWidth={3}
            fill="none"
            strokeLinecap="round"
            strokeLinejoin="round"
          />
        ))}
      </Svg>
    </View>
  );
}
 
const styles = StyleSheet.create({
  canvas: {
    flex: 1,
    backgroundColor: "#FAFAFA",
  },
});

// app/api/liveblocks-auth/route.ts (Next.js / Expo Router API route)
import { Liveblocks } from "@liveblocks/node";
import { createRouteHandlerClient } from "@supabase/auth-helpers-nextjs";
import { cookies } from "next/headers";
 
const liveblocks = new Liveblocks({
  secret: process.env.LIVEBLOCKS_SECRET_KEY!,
});
 
export async function POST(request: Request) {
  // 1. Verify the user's Supabase session
  const supabase = createRouteHandlerClient({ cookies });
  const { data: { session } } = await supabase.auth.getSession();
 
  if (!session) {
    return new Response("Unauthorized", { status: 401 });
  }
 
  // 2. Verify the user has access to the requested room
  const { room } = await request.json();
  const documentId = room.replace("document-", "");
 
  const { data: access } = await supabase
    .from("document_collaborators")
    .select("permission")
    .eq("document_id", documentId)
    .eq("user_id", session.user.id)
    .single();
 
  const { data: doc } = await supabase
    .from("documents")
    .select("owner_id, is_public")
    .eq("id", documentId)
    .single();
 
  const isOwner = doc?.owner_id === session.user.id;
  const isCollaborator = !!access;
  const isPublic = doc?.is_public;
 
  if (!isOwner && !isCollaborator && !isPublic) {
    return new Response("Forbidden", { status: 403 });
  }
 
  // 3. Issue a Liveblocks auth token
  const { body, status } = await liveblocks.identifyUser(
    {
      userId: session.user.id,
      groupIds: [],
    },
    {
      userInfo: {
        name: session.user.user_metadata?.full_name ?? "Anonymous",
        avatar: session.user.user_metadata?.avatar_url,
      },
    }
  );
 
  return new Response(body, { status });
}

// src/hooks/useUndoManager.ts
import { useEffect, useRef } from "react";
import * as Y from "yjs";
 
export function useUndoManager(yText: Y.Text) {
  const managerRef = useRef<Y.UndoManager | null>(null);
 
  useEffect(() => {
    // Track only changes to yText; ignore remote changes automatically
    const manager = new Y.UndoManager(yText, {
      // Merge operations within 500ms into a single undo step
      captureTimeout: 500,
    });
    managerRef.current = manager;
 
    return () => manager.destroy();
  }, [yText]);
 
  return {
    undo: () => managerRef.current?.undo(),
    redo: () => managerRef.current?.redo(),
    canUndo: () => (managerRef.current?.undoStack.length ?? 0) > 0,
    canRedo: () => (managerRef.current?.redoStack.length ?? 0) > 0,
  };
}

// tests/collaboration.test.ts
import * as Y from "yjs";
import { WebsocketProvider } from "y-websocket"; // local y-websocket server
 
test("two clients converge on the same text", async () => {
  const doc1 = new Y.Doc();
  const doc2 = new Y.Doc();
 
  // Simulate a peer-to-peer update exchange
  const text1 = doc1.getText("content");
  const text2 = doc2.getText("content");
 
  // Client 1 types "Hello"
  text1.insert(0, "Hello");
  Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1));
 
  // Client 2 types " World" concurrently
  text2.insert(5, " World");
  Y.applyUpdate(doc1, Y.encodeStateAsUpdate(doc2));
 
  // Both documents should converge
  expect(text1.toString()).toBe("Hello World");
  expect(text2.toString()).toBe("Hello World");
});

// Wrap the RoomProvider in an error boundary for graceful fallback
import { ErrorBoundary } from "react-error-boundary";
 
function CollaborationFallback() {
  return <OfflineEditor />; // Read-only fallback when Liveblocks is unavailable
}
 
export function CollaborationWrapper({ children }: { children: React.ReactNode }) {
  return (
    <ErrorBoundary FallbackComponent={CollaborationFallback}>
      {children}
    </ErrorBoundary>
  );
}

// Enforce collaborator limits based on the user's subscription tier
async function canAddCollaborator(
  documentId: string,
  ownerId: string
): Promise<boolean> {
  const { data: subscription } = await supabase
    .from("subscriptions")
    .select("plan")
    .eq("user_id", ownerId)
    .single();
 
  const { count } = await supabase
    .from("document_collaborators")
    .select("id", { count: "exact", head: true })
    .eq("document_id", documentId);
 
  const limits: Record<string, number> = {
    free: 3,
    pro: 25,
    team: Infinity,
  };
 
  const plan = subscription?.plan ?? "free";
  return (count ?? 0) < (limits[plan] ?? 3);
}