BlockSuite — Content Editing Toolkit for Building Collaborative Editors

Introduction

BlockSuite provides the editing infrastructure behind AFFiNE, the open-source Notion alternative. It separates the editing engine, block definitions, and collaboration layer into composable packages so developers can build custom block editors, whiteboards, or document tools without starting from scratch.

What BlockSuite Does

• Provides a CRDT-based document model for conflict-free real-time collaboration
• Ships pre-built blocks for paragraphs, headings, code, images, tables, and databases
• Supports a hybrid editing surface combining document and whiteboard modes
• Offers a framework-agnostic rendering layer using Web Components
• Enables custom block creation with a typed schema and lifecycle API

Architecture Overview

BlockSuite is organized into three layers. The store layer (@blocksuite/store) manages the CRDT-backed document model using Yjs, handling real-time sync and undo/redo. The blocks layer (@blocksuite/blocks) defines the visual and interactive behavior of each block type as Web Components. The presets layer (@blocksuite/presets) assembles blocks into ready-to-use editor configurations like the page editor and edgeless (whiteboard) editor.

Self-Hosting & Configuration

• Install via npm as modular packages; pick only the layers you need
• Use @blocksuite/presets for a complete editor or build custom setups with lower-level APIs
• Connect a Yjs provider (WebSocket, WebRTC, or IndexedDB) for collaboration and persistence
• Register custom block schemas to extend the editor with domain-specific content types
• Style blocks with CSS custom properties for theme integration

Key Features

• CRDT-native document model ensuring conflict-free collaboration out of the box
• Hybrid document and whiteboard editing in a single surface (edgeless mode)
• Web Component-based blocks that work with any frontend framework
• Drag-and-drop block reordering with nested block support
• Extensible slash menu, toolbar, and formatting popup system

Comparison with Similar Tools

• ProseMirror/TipTap — Schema-based rich text; BlockSuite adds block-level structure and CRDT collaboration
• Slate.js — Flexible editor framework; BlockSuite includes pre-built blocks and whiteboard mode
• Lexical — Meta's editor framework; BlockSuite provides a full block editing system, not just rich text
• Notion SDK — API for Notion's platform; BlockSuite lets you build your own Notion-like editor
• Yjs — CRDT library; BlockSuite uses Yjs internally and adds the editing UI layer on top

FAQ

Q: Can I use BlockSuite without AFFiNE? A: Yes. BlockSuite is a standalone toolkit. AFFiNE is one consumer; you can build entirely independent applications.

Q: Does it support real-time collaboration? A: Yes. The document model is CRDT-based (via Yjs), so you connect any Yjs provider for real-time multi-user editing.

Q: Can I create custom block types? A: Yes. Define a typed schema, implement a Web Component for rendering, and register it with the editor.

Q: What frameworks does it work with? A: BlockSuite uses Web Components, so it integrates with React, Vue, Svelte, Angular, or vanilla HTML.

Sources

• https://github.com/toeverything/blocksuite
• https://blocksuite.io