The BlockSuite project aims to provide a toolkit for building collaborative editors. It creates a tech stack suitable for general-purpose structured content editing, and builds upon that to implement various first-party editors. By leveraging blocks as the fundamental primitive, all BlockSuite-based editors share high compatibility, and can even be dynamically switched as different view layers at runtime.

⚠️ BlockSuite is already in use in the production environment of AFFiNE, but it's still under heavy development and undergoing rapid changes. Stay tuned or check out our roadmap!

BlockSuite was originally designed for the AFFiNE knowledge base. In AFFiNE, the same piece of data can be presented in various forms including documents, whiteboards, and tables. Users can smoothly switch among these different forms with real-time collaboration support. To this end, BlockSuite focuses on utilizing blocks as its primitive element to create a standardized collaborative editing engine. This consists of the following modules:

• ⚡️ CRDT-Driven Block State Management: The block tree model in BlockSuite is implemented using the Yjs CRDT library. Acting like a conflict-free Git, CRDT (conflict-free replicated data type) enables the editor to have built-in conflict resolution and time travel capabilities. By using CRDT as the single source of truth, all editors based on BlockSuite are natively collaborative. Plus, CRDT is blazingly fast.
• ⚛️ Atomic Block UI Components: In BlockSuite, blocks act like molecules, which can be further assembled from other blocks or more atomic components. These atomic components include rich-text and canvas renderers. For example, in BlockSuite, 100 paragraph blocks will generate 100 instances of rich-text components, and a form block could connect to multiple rich-text components. All these rich-text instances are linked to the same CRDT block tree, ensuring the cross-block editing operations can be consistently managed. Additionally, BlockSuite editors and blocks are all defined as Web Components, making them easily integratable with other frameworks.
• 🎨 Adaptable Selection Manager: BlockSuite models operations on abstract selection states, allowing for the extension of various types of selections that are well-suited for multi-user collaboration.
• 💾 Content Transformation and Serialization: BlockSuite supports JSON-based document snapshots and offers extensibility for compatibility with third-party formats. It also provides auxiliary tools for managing forward and backward compatibility, as well as data validation and migration issues.
• 📡 Providers for Data Synchronization: The document state in BlockSuite can be serialized into binary and distributed through various providers, allowing for transmission via WebSocket, or storage into persistent backends like SQLite or IndexedDB. Thanks to their support for on-demand loading and incremental updates, these providers work efficiently.

Based on this framework, BlockSuite has already implemented editing capabilities for various types of structured data:

• Rich text editor
• Whiteboard editor
• Table editing with kanban view support

• 🎁 Examples
  • Nightly Playground
  • The SimpleAffineEditor Example
  • BlockSuite Monorepo in StackBlitz
  • Vue-based BlocksVite Editor
• 🚧 Documentation
• 🗓️ GitHub Project
• 📍 GitHub Issues
• 🎙️ GitHub Discussions
• 💬 Discord Channel
• 🏠 AFFiNE Community
• 🚀 Releases

To learn how to start using BlockSuite, visit blocksuite.affine.pro.

See BUILDING.md for instructions on how to build BlockSuite from source code.

BlockSuite accepts pull requests on GitHub. Before you start contributing, please make sure you have read and accepted our Contributor License Agreement. To indicate your agreement, simply edit this file and submit a pull request.

MPL 2.0