https://github.com/typecellos/blocknote-electric-example
https://github.com/typecellos/blocknote-electric-example
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/typecellos/blocknote-electric-example
- Owner: TypeCellOS
- Created: 2025-07-21T11:15:10.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-09-23T08:57:11.000Z (4 months ago)
- Last Synced: 2025-09-23T10:26:41.204Z (4 months ago)
- Language: TypeScript
- Homepage: https://blocknote-electric-example.vercel.app
- Size: 152 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# BlockNote + Electric SQL: Real-time Collaborative Rich Text Editing
This example showcases a multiplayer [BlockNote](https://blocknotejs.org/) rich text editor with [YJS](https://github.com/yjs/yjs) and [Electric SQL](https://electric-sql.com/). All collaborative data is synchronized through [PostgreSQL](https://www.postgresql.org/), 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](https://blocknotejs.org/)**: A modern, extensible rich text editor built on ProseMirror
- **[YJS](https://github.com/yjs/yjs)**: A CRDT library that enables real-time collaboration
- **[Electric SQL](https://electric-sql.com/)**: A local-first database that syncs with PostgreSQL
- **[Y-Electric](https://github.com/electric-sql/electric/tree/main/packages/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](https://nodejs.org/) (v18 or higher)
- [pnpm](https://pnpm.io/) (v8 or higher)
- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/)
### Installation
1. Install dependencies:
```shell
pnpm install
```
2. Build the application:
```shell
pnpm build
```
### Running the Application
1. Start the backend services using Docker Compose:
```shell
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:
```shell
pnpm dev:server
```
3. In a new terminal, start the client application:
```shell
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:
```shell
pnpm backend:down
```
## 🔧 Key Components
### BlockNote Integration
The editor is implemented in `src/client/components/editor/EditorView.tsx`:
```typescript
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`:
```typescript
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](https://blocknotejs.org/docs)
- [YJS Documentation](https://docs.yjs.dev/)
- [Electric SQL Documentation](https://electric-sql.com/docs)
- [Y-Electric Package](https://github.com/electric-sql/electric/tree/main/packages/y-electric)
## 🤝 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](https://github.com/TypeCellOS/BlockNote)
- **Electric SQL**: Visit the [Electric SQL repository](https://github.com/electric-sql/electric)
- **This Example**: [Open an issue](https://github.com/TypeCellOS/blocknote-electric-example/issues)
## 📄 License
This project is licensed under the Apache 2.0 License.