Real-Time Collaboration Engine

Expert in building Google Docs-style collaborative editing with WebSockets, conflict resolution, and presence awareness.

When to Use

✅ Use for:

Collaborative text/code editors Shared whiteboards and design tools Multi-user video editing timelines Real-time data dashboards Multiplayer game state sync

❌ NOT for:

Simple chat applications (use basic WebSocket) Request-response APIs (use REST/GraphQL) Single-user applications Read-only data streaming (use Server-Sent Events) Quick Decision Tree Need real-time collaboration? ├── Text editing? → Operational Transform (OT) ├── JSON data structures? → CRDTs ├── Cursor tracking only? → Simple WebSocket + presence ├── Offline-first? → CRDTs (better offline merge) └── No conflicts possible? → Basic broadcast

Technology Selection Conflict Resolution Strategies (2024) Strategy Best For Complexity Offline Support Operational Transform (OT) Text, ordered sequences High Limited CRDTs JSON objects, sets Medium Excellent Last-Write-Wins Simple state Low Basic Three-Way Merge Git-style editing High Good

Timeline:

2010: Google Wave uses OT 2014: Figma adopts CRDTs 2019: Yjs (CRDT library) released 2022: Automerge 2.0 (CRDT library) released 2024: PartyKit simplifies real-time infrastructure Common Anti-Patterns Anti-Pattern 1: Broadcasting Every Keystroke

Novice thinking: "Send every change immediately for real-time feel"

Problem: Network floods with tiny messages, poor performance.

Wrong approach:

// ❌ Sends message on every keystroke function Editor() { const handleChange = (text: string) => { socket.emit('text-change', { text }); // Every keystroke! };

return handleChange(e.target.value)} />; } Why wrong: 100 WPM typing = 500 messages/minute = network congestion. Correct approach: // ✅ Batches changes every 200ms function Editor() { const [pendingChanges, setPendingChanges] = useState<Change[]>([]); useEffect(() => { const interval = setInterval(() => { if (pendingChanges.length > 0) { socket.emit('text-batch', { changes: pendingChanges }); setPendingChanges([]); } }, 200); <pre class="codehilite"><code>return () => clearInterval(interval); </code></pre> }, [pendingChanges]); const handleChange = (change: Change) => { setPendingChanges(prev => [...prev, change]); }; return <textarea onChange={handleChange} />; } Impact: 500 messages/minute → 5 messages/second (90% reduction). Anti-Pattern 2: No Conflict Resolution Strategy Problem: Concurrent edits cause data loss or corruption. Symptom: Users see their changes disappear, documents become inconsistent. Wrong approach: // ❌ Last write wins, overwrites concurrent changes socket.on('text-change', ({ userId, text }) => { setDocument(text); // Loses concurrent edits! }); Why wrong: If User A and B edit simultaneously, one change is lost. Correct approach (OT): // ✅ Operational Transform for text import { TextOperation } from 'ot.js'; socket.on('operation', ({ userId, operation, revision }) => { const transformed = transformOperation( operation, pendingOperations, revision ); applyOperation(transformed); incrementRevision(); }); function transformOperation( incoming: Operation, pending: Operation[], baseRevision: number ): Operation { // Transform incoming against pending operations let transformed = incoming; for (const op of pending) { transformed = TextOperation.transform(transformed, op)[0]; } return transformed; } Correct approach (CRDT): // ✅ CRDT for JSON objects import * as Y from 'yjs'; const ydoc = new Y.Doc(); const ytext = ydoc.getText('document'); // Automatically handles conflicts ytext.insert(0, 'Hello'); // Sync with peers const provider = new WebsocketProvider('ws://localhost:1234', 'room', ydoc); Impact: Concurrent edits merge correctly, no data loss. Anti-Pattern 3: Not Handling Disconnections Problem: User goes offline, loses work or sees stale state. Wrong approach: // ❌ No offline handling socket.on('disconnect', () => { console.log('Disconnected'); // That's it?! }); Why wrong: Pending changes lost, no reconnection strategy, bad UX. Correct approach: // ✅ Queue changes offline, sync on reconnect const [isOnline, setIsOnline] = useState(true); const [offlineQueue, setOfflineQueue] = useState<Change[]>([]); socket.on('disconnect', () => { setIsOnline(false); showToast('Offline - changes will sync when reconnected'); }); socket.on('connect', () => { setIsOnline(true); // Send queued changes if (offlineQueue.length > 0) { socket.emit('sync-offline-changes', { changes: offlineQueue }); setOfflineQueue([]); } }); const handleChange = (change: Change) => { if (isOnline) { socket.emit('change', change); } else { setOfflineQueue(prev => [...prev, change]); } }; Timeline context: 2015: Offline-first apps rare 2020: PWAs make offline UX standard 2024: Users expect seamless offline editing Anti-Pattern 4: Client-Only State Sync Problem: No server authority, clients get out of sync. Wrong approach: // ❌ Clients broadcast to each other directly socket.on('peer-change', ({ userId, change }) => { applyChange(change); // No validation, no server state }); Why wrong: Malicious client can send invalid data, no recovery from desync. Correct approach: // ✅ Server is source of truth // Client socket.emit('operation', { operation, clientRevision }); socket.on('ack', ({ serverRevision }) => { if (serverRevision !== expectedRevision) { // Desync detected, request full state socket.emit('request-full-state'); } }); // Server io.on('connection', (socket) => { socket.on('operation', ({ operation, clientRevision }) => { // Validate operation if (!isValid(operation)) { socket.emit('error', { message: 'Invalid operation' }); return; } <pre class="codehilite"><code>// Apply to server state const serverRevision = applyOperation(operation); // Broadcast to all clients io.emit('operation', { operation, serverRevision }); </code></pre> }); }); Impact: Data integrity guaranteed, can recover from client bugs. Anti-Pattern 5: No Presence Awareness Problem: Users can't see who's editing what, causing edit conflicts. Symptom: Two people editing same section unknowingly. Wrong approach: // ❌ No awareness of other users function Editor() { return <textarea />; // Flying blind! } Correct approach: // ✅ Show active users and cursors import { usePresence } from './usePresence'; function Editor() { const { users, updateCursor } = usePresence(); const handleCursorMove = (position: number) => { socket.emit('cursor-move', { userId: myId, position }); }; return ( <div> {/ Show who's online /} <UserList users={users} /> <pre class="codehilite"><code> {/* Show remote cursors */} <EditorWithCursors content={content} cursors={users.map(u => u.cursor)} onCursorMove={handleCursorMove} /> </div> </code></pre> ); } Features: Active user list with avatars Cursor positions color-coded by user Selection ranges highlighted "User X is typing..." indicators Implementation Patterns Pattern 1: WebSocket Setup with Reconnection import { io } from 'socket.io-client'; const socket = io('ws://localhost:3000', { reconnection: true, reconnectionDelay: 1000, reconnectionDelayMax: 5000, reconnectionAttempts: Infinity, transports: ['websocket', 'polling'] // Fallback }); socket.on('connect', () => { console.log('Connected:', socket.id); }); socket.on('disconnect', (reason) => { if (reason === 'io server disconnect') { // Server disconnected, manually reconnect socket.connect(); } }); socket.on('connect_error', (error) => { console.error('Connection error:', error); }); Pattern 2: Operational Transform (Text) import { TextOperation } from 'ot.js'; class OTEditor { private revision = 0; private pendingOperations: TextOperation[] = []; applyLocalOperation(op: TextOperation): void { // Apply immediately (optimistic update) this.applyToEditor(op); <pre class="codehilite"><code>// Send to server this.sendOperation(op); // Store as pending this.pendingOperations.push(op); </code></pre> } receiveRemoteOperation(op: TextOperation, serverRevision: number): void { // Transform against pending operations let transformed = op; for (const pending of this.pendingOperations) { [transformed, pending] = TextOperation.transform(transformed, pending); } <pre class="codehilite"><code>// Apply transformed operation this.applyToEditor(transformed); this.revision = serverRevision; </code></pre> } acknowledgeOperation(serverRevision: number): void { // Remove acknowledged operation from pending this.pendingOperations.shift(); this.revision = serverRevision; } } Pattern 3: CRDT with Yjs import * as Y from 'yjs'; import { WebsocketProvider } from 'y-websocket'; // Create shared document const ydoc = new Y.Doc(); // Define shared types const ytext = ydoc.getText('content'); const ymap = ydoc.getMap('metadata'); const yarray = ydoc.getArray('users'); // Connect to sync server const provider = new WebsocketProvider( 'ws://localhost:1234', 'room-name', ydoc ); // Listen to changes ytext.observe(event => { console.log('Text changed:', event.changes); }); // Make changes (automatically synced) ytext.insert(0, 'Hello '); ytext.insert(6, 'World!'); // Undo/redo support const undoManager = new Y.UndoManager(ytext); undoManager.undo(); undoManager.redo(); Pattern 4: Presence Awareness import { Awareness } from 'y-protocols/awareness'; const awareness = provider.awareness; // Set local state awareness.setLocalState({ user: { name: 'Alice', color: '#ff0000', cursor: { line: 10, ch: 5 } } }); // Listen to changes awareness.on('change', ({ added, updated, removed }) => { // Update UI with user cursors/selections const states = awareness.getStates(); states.forEach((state, clientId) => { if (clientId !== awareness.clientID) { renderCursor(state.user.cursor, state.user.color); } }); }); Pattern 5: Optimistic Updates with Rollback class OptimisticEditor { private optimisticChanges = new Map<string, Change>(); async applyChange(change: Change): Promise<void> { const changeId = generateId(); <pre class="codehilite"><code>// Apply immediately (optimistic) this.applyToUI(change); this.optimisticChanges.set(changeId, change); try { // Send to server const result = await this.sendToServer(change); // Success - remove from optimistic this.optimisticChanges.delete(changeId); } catch (error) { // Failed - rollback this.rollback(changeId); this.showError('Could not apply change'); } </code></pre> } private rollback(changeId: string): void { const change = this.optimisticChanges.get(changeId); if (change) { this.revertInUI(change); this.optimisticChanges.delete(changeId); } } } Production Checklist □ WebSocket connection with auto-reconnect □ Offline queue for pending changes □ Conflict resolution strategy (OT or CRDT) □ Server authority (clients can't desync) □ Presence awareness (cursors, active users) □ Optimistic updates with rollback □ Change batching (not per-keystroke) □ Message compression for large payloads □ Authentication and authorization □ Rate limiting (prevent spam) □ Heartbeat/ping-pong to detect dead connections □ Graceful degradation (falls back to polling if WebSocket fails) When to Use vs Avoid Scenario Strategy Text editing (Google Docs) ✅ Operational Transform JSON objects (Figma) ✅ CRDTs (Yjs, Automerge) Simple cursor sharing ✅ Basic WebSocket + presence Chat messages ✅ Simple append-only (no OT/CRDT) Video timeline editing ✅ CRDTs for timeline, OT for text Read-only dashboards ❌ Use Server-Sent Events instead References /references/ot-vs-crdt.md - Deep comparison of conflict resolution strategies /references/websocket-scaling.md - Scaling to millions of concurrent connections /references/presence-patterns.md - Cursor tracking, user awareness, activity indicators Scripts scripts/collaboration_tester.ts - Simulate concurrent edits, test conflict resolution scripts/latency_simulator.ts - Test behavior under high latency/packet loss This skill guides: Real-time collaboration | WebSocket architecture | Operational Transform | CRDTs | Presence awareness | Conflict resolution </article> <a href="/" class="back-link">← 返回排行榜</a> </div> <aside class="sidebar"> <section class="related-skills" id="relatedSkillsSection"> <h2 class="related-title" data-i18n="detail.relatedSkills">相关 Skills</h2> <div class="related-list" id="relatedSkillsList"> <div class="skeleton-card"></div> <div class="skeleton-card"></div> <div class="skeleton-card"></div> </div> </section> </aside> </div> </div> <script src="https://unpkg.com/i18next@23.11.5/i18next.min.js" defer></script> <script src="https://unpkg.com/i18next-browser-languagedetector@7.2.1/i18nextBrowserLanguageDetector.min.js" defer></script> <script defer> // Language resources - same pattern as index page const resources = { 'zh-CN': null, 'en': null, 'ja': null, 'ko': null, 'zh-TW': null, 'es': null, 'fr': null }; // Load language files (only current + fallback for performance) async function loadLanguageResources() { const savedLang = localStorage.getItem('i18nextLng') || 'en'; const langsToLoad = new Set([savedLang, 'en']); // current + fallback await Promise.all([...langsToLoad].map(async (lang) => { try { const response = await fetch(`/locales/${lang}.json`); if (response.ok) { resources[lang] = { translation: await response.json() }; } } catch (error) { console.warn(`Failed to load ${lang} language file:`, error); } })); } // Load a single language on demand (for language switching) async function loadLanguage(lang) { if (resources[lang]) return; try { const response = await fetch(`/locales/${lang}.json`); if (response.ok) { resources[lang] = { translation: await response.json() }; i18next.addResourceBundle(lang, 'translation', resources[lang].translation); } } catch (error) { console.warn(`Failed to load ${lang} language file:`, error); } } // Initialize i18next async function initI18n() { try { await loadLanguageResources(); // Filter out null values from resources const validResources = {}; for (const [lang, data] of Object.entries(resources)) { if (data !== null) { validResources[lang] = data; } } console.log('Loaded languages:', Object.keys(validResources)); console.log('zh-CN resource:', validResources['zh-CN']); console.log('detail.home in resource:', validResources['zh-CN']?.translation?.detail?.home); // 检查是否有保存的语言偏好 const savedLang = localStorage.getItem('i18nextLng'); // 如果没有保存的语言偏好，默认使用英文 const defaultLang = savedLang && ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'].includes(savedLang) ? savedLang : 'en'; await i18next .use(i18nextBrowserLanguageDetector) .init({ lng: defaultLang, // 强制设置初始语言 fallbackLng: 'en', supportedLngs: ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'], resources: validResources, detection: { order: ['localStorage'], // 只使用 localStorage，不检测浏览器语言 caches: ['localStorage'], lookupLocalStorage: 'i18nextLng' }, interpolation: { escapeValue: false } }); console.log('i18next initialized, language:', i18next.language); console.log('Test translation:', i18next.t('detail.home')); // Set initial language in selector const langSwitcher = document.getElementById('langSwitcher'); langSwitcher.value = i18next.language; // Update page language updatePageLanguage(); // Language switch event langSwitcher.addEventListener('change', async (e) => { await loadLanguage(e.target.value); // load on demand i18next.changeLanguage(e.target.value).then(() => { updatePageLanguage(); localStorage.setItem('i18nextLng', e.target.value); }); }); } catch (error) { console.error('i18next init failed:', error); } } // Translation helper function t(key, options = {}) { return i18next.t(key, options); } // Update all translatable elements function updatePageLanguage() { // Update HTML lang attribute document.documentElement.lang = i18next.language; // Update elements with data-i18n attribute document.querySelectorAll('[data-i18n]').forEach(el => { const key = el.getAttribute('data-i18n'); el.textContent = t(key); }); } // Copy command function function copyCommand() { const command = document.getElementById('installCommand').textContent; const btn = document.getElementById('copyBtn'); navigator.clipboard.writeText(command).then(() => { btn.textContent = t('copied'); btn.classList.add('copied'); setTimeout(() => { btn.textContent = t('copy'); btn.classList.remove('copied'); }, 2000); }).catch(() => { // Fallback for non-HTTPS const textArea = document.createElement('textarea'); textArea.value = command; textArea.style.position = 'fixed'; textArea.style.left = '-9999px'; document.body.appendChild(textArea); textArea.select(); document.execCommand('copy'); document.body.removeChild(textArea); btn.textContent = t('copied'); btn.classList.add('copied'); setTimeout(() => { btn.textContent = t('copy'); btn.classList.remove('copied'); }, 2000); }); } // Initialize document.getElementById('copyBtn').addEventListener('click', copyCommand); initI18n(); // 异步加载相关 Skills async function loadRelatedSkills() { const owner = 'erichowens'; const skillName = 'real-time-collaboration-engine'; const currentLang = 'ko'; const listContainer = document.getElementById('relatedSkillsList'); const section = document.getElementById('relatedSkillsSection'); try { const response = await fetch(`/api/related-skills/${encodeURIComponent(owner)}/${encodeURIComponent(skillName)}?limit=6`); if (!response.ok) { throw new Error('Failed to load'); } const data = await response.json(); const relatedSkills = data.related_skills || []; if (relatedSkills.length === 0) { // 没有相关推荐时隐藏整个区域 section.style.display = 'none'; return; } // 渲染相关 Skills listContainer.innerHTML = relatedSkills.map(skill => { const desc = skill.description || ''; const truncatedDesc = desc.length > 60 ? desc.substring(0, 60) + '...' : desc; return ` <a href="${currentLang === 'en' ? '' : '/' + currentLang}/skill/${skill.owner}/${skill.repo}/${skill.skill_name}" class="related-card"> <div class="related-name">${escapeHtml(skill.skill_name)}</div> <div class="related-meta"> ${escapeHtml(skill.owner)} ${skill.installs} </div> <div class="related-desc">${escapeHtml(truncatedDesc)}</div> </a> `; }).join(''); } catch (error) { console.error('Failed to load related skills:', error); // 加载失败时显示提示或隐藏 listContainer.innerHTML = '<div class="related-empty">暂无相关推荐</div>'; } } // HTML 转义 function escapeHtml(text) { const div = document.createElement('div'); div.textContent = text; return div.innerHTML; } // 页面加载完成后异步加载相关 Skills if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', loadRelatedSkills); } else { loadRelatedSkills(); } </script> </body> </html>

安装