BlockSuite Overview

BlockSuite is a toolkit for building diverse collaborative editors and applications. It implements a series of collaborative editing infrastructures and editors independently. With BlockSuite, you can choose to:

• Reuse multiple first-party BlockSuite editors right out of the box:
  • DocEditor: Built entirely from scratch, DocEditor is a comprehensive block-based document editor, offering extensive customization and flexibility.
  • EdgelessEditor: Featuring canvas-based graphics rendering at its core with sophisticated rich-text features, EdgelessEditor offers unique functionalities and decent performance in whiteboard editing.
• Or, build new editors from scratch based on the underlying vallina framework.

First party BlockSuite editors are being used in AFFiNE, click 🔁 in following example to switch between them dynamically - they are fully compatible!

🚧 BlockSuite is currently in its early stage, with components and extension capabilities still under refinement. Hope you can stay tuned, try it out, or share your feedback!

In addition to extending custom blocks, here are what you can also conveniently achieve with BlockSuite:

• Incremental updates, real-time collaboration, local-first state management, and even decentralized data synchronization based on the document streaming mechanism.
• Writing type-safe complex editing logic based on the command mechanism, similar to react hooks designed for document editing.
• Persistence of documents and compatibility with various third-party formats (such as markdown and HTML) based on block snapshot and transformer.
• State scheduling across multiple documents and reusing one document in multiple editors.

To try out BlockSuite, refer to the Quick Start document and start with the preset editors in @blocksuite/presets.

---

The BlockSuite project is structured around key packages that are categorized into two groups: a headless framework and prebuilt editing components.

Headless Framework
@blocksuite/store	Data layer for modeling collaborative document states. It is natively built on the CRDT library Yjs, powering all BlockSuite documents with built-in real-time collaboration and time-travel capabilities.
@blocksuite/inline	Minimal rich text components for inline editing. BlockSuite allows spliting rich text content in different block nodes into different inline editors, making complex content conveniently composable. This significantly reduces the complexity required to implement traditional rich text editing features.
@blocksuite/block-std	Framework-agnostic library for modeling editable blocks. Its capabilities cover the structure of block fields, events, selection, clipboard support, etc.
@blocksuite/lit	Intermediate layer for adapting the block tree to the lit framework component tree UI. BlockSuite uses lit as the default framework because lit components are native web components, avoiding synchronization issues between the component tree and DOM tree during complex editing.

Prebuilt Components
@blocksuite/blocks	Default block implementations for composing preset editors, including widgets belonging to each block.
@blocksuite/presets	Plug-and-play editable components including editors (DocEditor / EdgelessEditor) and auxiliary UI components named fragments (CopilotPanel, DocTitle...).

This can be illustrated as the diagram below: