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:
- Build a new editor from scratch based on the BlockSuite framework.
- Or, reuse multiple first-party editors based on BlockSuite right out of the box:
DocEditor: Built entirely from scratch,DocEditoris 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,EdgelessEditoroffers unique functionalities and decent performance in whiteboard editing.
These editors are being used in AFFiNE.
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 of the document.
- 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:
🚧 BlockSuite is currently in its early stage, with some extension capabilities still under refinement. Hope you can stay tuned, try it out, or share your feedback!
- 🎁 Examples
- 📝 Documentation
- 📍 Good First Issues
- 🎙️ GitHub Discussions
- 💬 Discord Channel
- 🚀 Releases
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.