BlockNote + Electric SQL: Real-time Collaborative Rich Text Editing

This example showcases a multiplayer BlockNote rich text editor with YJS and Electric SQL. All collaborative data is synchronized through PostgreSQL, providing real-time editing with cursor awareness without requiring additional real-time infrastructure.

🚀 Features

• Real-time Collaborative Editing: Multiple users can edit documents simultaneously
• Cursor Awareness: See other users' cursors and selections in real-time
• Rich Text Editor: Full-featured editor based on ProseMirror with BlockNote
• Offline Support: Works offline with automatic sync when reconnected
• CRDT-based: Conflict-free editing using YJS CRDT technology
• Database-backed: All data persisted in PostgreSQL with Electric SQL

🏗️ Architecture

This application demonstrates the powerful combination of:

• BlockNote: A modern, extensible rich text editor built on ProseMirror
• YJS: A CRDT library that enables real-time collaboration
• Electric SQL: A local-first database that syncs with PostgreSQL
• Y-Electric: A YJS connection provider that integrates YJS with Electric SQL

The integration works by:

1. BlockNote uses YJS for collaborative editing via the y-prosemirror binding
2. Y-Electric handles the synchronization between YJS documents and PostgreSQL
3. Electric SQL provides offline-first database capabilities with automatic sync
4. All collaboration data flows through PostgreSQL, eliminating the need for WebSocket servers

🛠️ Setup

Prerequisites

• Node.js (v18 or higher)
• pnpm (v8 or higher)
• Docker and Docker Compose

Installation

1. Install dependencies:

   pnpm install

2. Build the application:

   pnpm build

Running the Application

1. Start the backend services using Docker Compose:

   pnpm backend:up

   Note: This stops and deletes volumes from any other running example backend containers to ensure a clean database state.

2. Start the development server:

   pnpm dev:server

3. In a new terminal, start the client application:

   pnpm dev:client

4. Open your browser and navigate to the application URL (typically http://localhost:5173)

5. When you're done, stop the backend services:

   pnpm backend:down

🔧 Key Components

BlockNote Integration

The editor is implemented in src/client/components/editor/EditorView.tsx:

const editor = useCreateBlockNote({
  collaboration: {
    provider: {
      awareness, // YJS awareness for cursor/selection sync
    },
    fragment: ydoc.getXmlFragment(`document-store`), // YJS fragment for document data
    user: {
      name: user.name,
      color: user.color,
    },
  },
})

Electric SQL Integration

The YJS-Electric integration is handled in src/client/common/useElectric.ts:

const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: {
    shape: { /* Electric SQL shape configuration */ },
    sendUrl: /* API endpoint for updates */,
  },
  awarenessUpdates: {
    shape: { /* Awareness sync configuration */ },
    sendUrl: /* API endpoint for awareness updates */,
  },
})

Database Schema

The PostgreSQL schema (db/migrations/01-create_yjs_tables.sql) includes:

• ydoc_update: Stores YJS document updates
• ydoc_awareness: Stores user awareness data (cursors, selections)
• files: Document metadata
• users: User information

🎯 Usage

1. Create a User: Select a user from the dropdown in the sidebar
2. Edit Documents: Start typing in the editor - changes sync in real-time
3. Collaborate: Open multiple browser tabs/windows with different users to see real-time collaboration
4. Cursor Awareness: See other users' cursors and selections in real-time
5. Offline Mode: Disconnect and continue editing - changes sync when reconnected

🔍 How It Works

1. Document Creation: Each document is represented as a YJS document with an XML fragment
2. Real-time Sync: Y-Electric syncs YJS updates with PostgreSQL via Electric SQL
3. Awareness: User cursors and selections are synced through the awareness protocol
4. Conflict Resolution: YJS CRDT automatically resolves conflicts between concurrent edits
5. Offline Support: Changes are stored locally and synced when connectivity is restored

📚 Learn More

• BlockNote Documentation
• YJS Documentation
• Electric SQL Documentation
• Y-Electric Package

🤝 Contributing

This is an example application demonstrating the integration of BlockNote with Electric SQL. For issues or contributions related to:

• BlockNote: Visit the BlockNote repository
• Electric SQL: Visit the Electric SQL repository
• This Example: Open an issue

📄 License

This project is licensed under the Apache 2.0 License.