✍️ 🦜 Lexical Loro - Collaborative Plugin for Lexical with Loro CRDT

A collaborative editing plugin for Lexical Rich Editor built with Loro CRDT, providing real-time collaborative editing capabilities with conflict-free synchronization.

Core Components

This package provides three main components for building collaborative text editors:

1. LoroCollaborativePlugin.tsx - A Lexical plugin that integrates Loro CRDT for real-time collaborative editing
2. LexicalModel Python Library - A standalone document model for Lexical content with CRDT capabilities
3. lexical-loro WebSocket Server - A Python server using loro-py for real-time collaboration

Quick Start

$3

``tsx
import { LoroCollaborativePlugin } from './src/LoroCollaborativePlugin';

function MyEditor() {
return (


websocketUrl="ws://localhost:8081"
docId="my-document"
username="user1"
/>

);
}
`

$3

`python
from lexical_loro import LexicalModel

Create a new document

`bash


Install the Python package

For complete working examples, see the src/examples/ directory which contains:
- Full React application with dual editor support
- Server selection interface
- Connection status indicators
- Rich text formatting examples

DISCLAIMER Collaborative Cursors still need fixes, see this issue.





Core Features

- 🔄 Real-time Collaboration: Multiple users can edit the same document simultaneously
- 🚀 Conflict-free: Uses Loro CRDT to automatically resolve conflicts
- 📝 Lexical Integration: Seamless integration with Lexical rich text editor
- 📚 Standalone Library: Use LexicalModel independently for document management
- 🌐 WebSocket Server: Python server for maintaining document state
- 📡 Connection Management: Robust WebSocket connection handling
- ✨ Rich Text Support: Preserves formatting during collaborative editing
- 💾 Serialization: JSON export/import and file persistence
- 🔧 Extensible: Plugin-based architecture for easy customization

Technology Stack

Core Dependencies:
- Lexical: v0.33.1 (Facebook's extensible text editor framework)
- Loro CRDT: v1.5.10 (Conflict-free replicated data types)
- React: 18/19 (for plugin hooks and components)
- Python: 3.8+ with loro-py and websockets

Development Dependencies:
- TypeScript: For type safety
- Vite: For building and development (examples only)
- pytest: Python testing
- ESLint: Code linting

Installation

$3

The Lexical plugin is a single TypeScript/React component that you can copy into your project:

`bash


Copy the plugin file

Dependencies required:
`bash
npm install lexical @lexical/react @lexical/selection loro-crdt react react-dom
`

$3

Install the Python WebSocket server:

`bash


Install from this repository

`tsx
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { LoroCollaborativePlugin } from './LoroCollaborativePlugin';

const editorConfig = {
namespace: 'MyEditor',
theme: {},
onError: console.error,
};

function CollaborativeEditor() {
return (



`python
from lexical_loro import LexicalModel

Create a new document

For more examples, see:
- examples/memory_only_example.py - Basic document creation and manipulation
- examples/file_sync_example.py - File persistence and batch operations
- examples/collaboration_example.py - Simulating collaborative editing
- docs/LEXICAL_MODEL_GUIDE.md - Comprehensive documentation

$3

Start the WebSocket server:

`bash


Default port (8081)

`python
import asyncio
from lexical_loro import LoroWebSocketServer

async def main():
server = LoroWebSocketServer(port=8081)
await server.start()
print("Server running on ws://localhost:8081")

if __name__ == "__main__":
asyncio.run(main())
`

Plugin API

For detailed API documentation, see docs/API.md.

$3

`tsx
interface LoroCollaborativePluginProps {
websocketUrl: string; // WebSocket server URL
docId: string; // Unique document identifier
username: string; // User identifier
userColor?: string; // User cursor color (optional)
debug?: boolean; // Enable debug logging (optional)
}
`

Initialization Best Practices

⚠️ Important: Always wait for collaboration initialization before enabling other plugins.

See docs/INITIALIZATION_GUIDE.md for comprehensive guidance on:
- Proper plugin ordering
- Initialization callbacks
- Error handling
- Common anti-patterns to avoid

Examples

For complete working examples and demonstrations, see the src/examples/ directory:

`bash


Run the example application

See src/examples/README.md for detailed example documentation.

Architecture

`
EDITOR 1 EDITOR 2

loro loro
- node(data: root(1)) - node(data: root(12))
- node(data: element(2)) - node(data: element(22))
- node(data: text(3)) - node(data: text(13))
- node(data: counter(4)) - node(data: counter(4))

<---- loro updates via websocket ------>
<---- loro node ids are the same ------>
<---- lexical node keys are different ------>

lexical lexical
- root(1) - root(12)
- element(2) - element(22)
- text(3) - text(13)
- counter(4) - counter(49)
``

Examples

Loro examples

- http://localhost:3000/?isCollab=true

- http://localhost:3000/split/?isCollab=true

Y.js examples (for reference)

- http://localhost:3000/?isCollab=true&useYjs=true

- http://localhost:3000/split/?isCollab=true&useYjs=true