BlockSuite (pronounced "block sweet") is the open-source editor project behind AFFiNE. It provides an out-of-the-box block-based editor built on top of a framework designed for general-purpose collaborative applications. This monorepo maintains both the editor and the underlying framework.
⚠️ This project is under heavy development and is in a stage of rapid evolution. Stay tuned or see our roadmap here!
BlockSuite works very differently than traditional rich text frameworks:
- For the data model, BlockSuite eliminates the need to work with data-driven DSLs (e.g., operations, actions, commands, transforms). Instead, it utilizes CRDT as the single source of truth, offering a strongly-typed block tree model built on Yjs. With BlockSuite, manipulating blocks becomes as simple as updating a todo list. Moreover, by fully harnessing the power of CRDT, it supports zero-cost time travel, real-time collaboration, and out-of-the-box pluggable persistence backends.
- For rich text editing, BlockSuite seamlessly organizes rich text content into discrete blocks. In BlockSuite, a document with 100 paragraphs can be rendered into 100 text blocks or 100 individual rich text editor instances, effectively eliminating the outdated practice of consolidating all content into a single, risky
contenteditablemonolith. - At the rendering layer, BlockSuite remains framework agnostic. It doesn't limit the block tree rendering to the DOM. Not only does it implement its entire document editing UI using Web Components, but it also offers a hybrid canvas-based renderer for whiteboard content sections. Both renderers can coexist on the same page and share a unified centralized data store.
BlockSuite is not intended to be yet another plugin-based rich text editing framework. Instead, it encourages building various collaborative applications directly through whatever UI framework you're comfortable with. To this end, we will try to open-source more foundational modules as reusable packages for this in the BlockSuite project.
Although BlockSuite is still in its early stages, you can already use the @blocksuite/editor package, the collaborative editor used in AFFiNE Alpha. Note that this editor is also a web component and is completely framework-independent!
- 🎁 Examples
- 🗓️ GitHub Project
- 📍 GitHub Issues
- 🎙️ GitHub Discussions
- 💬 Discord Channel
- 🏠 AFFiNE Community
- 🚀 Releases
The @blocksuite/editor package contains the editor built into AFFiNE. Its nightly versions are released daily based on the master branch, and they are always tested on CI. This means that the nightly versions can already be used in real-world projects like AFFiNE at any time:
pnpm i @blocksuite/editor@nightlyIf you want to easily reuse most of the rich-text editing features, you can use the SimpleAffineEditor web component directly (code example here):
import { SimpleAffineEditor } from '@blocksuite/editor';
import '@blocksuite/editor/themes/affine.css';
const editor = new SimpleAffineEditor();
document.body.appendChild(editor);Or equivalently, you can also use the declarative style:
<body>
<simple-affine-editor></simple-affine-editor>
<script type="module">
import '@blocksuite/editor';
import '@blocksuite/editor/themes/affine.css';
</script>
</body>👉 Try SimpleAffineEditor online
However, the SimpleAffineEditor here is just a thin wrapper with dozens of lines that doesn't enable the opt-in collaboration and data persistence features. If you are going to support more complicated real-world use cases (e.g., with customized block models and configured data sources), this will involve the use of these three following core packages:
- The
packages/storepackage is a data store built for general-purpose state management. - The
packages/blockspackage holds the default BlockSuite editable blocks. - The
packages/editorpackage ships a complete BlockSuite-based editor.
pnpm i \
@blocksuite/store@nightly \
@blocksuite/blocks@nightly \
@blocksuite/editor@nightlyAnd here is a minimal collaboration-ready editor showing how these underlying BlockSuite packages are composed together:
🚧 Here we will work with the concepts of
Workspace,Page,BlockandSlot. These are the primitives for building a block-based collaborative application. We are preparing a comprehensive documentation about their usage!
import '@blocksuite/blocks';
import { Workspace, Page } from '@blocksuite/store';
import { AffineSchemas } from '@blocksuite/blocks/models';
import { EditorContainer } from '@blocksuite/editor';
function main() {
// Create a workspace with one default page
const workspace = new Workspace({ id: 'test' }).register(AffineSchemas);
const page = workspace.createPage('page0');
// Create default blocks in the page
const pageBlockId = page.addBlock('affine:page');
const frameId = page.addBlock('affine:frame', {}, pageBlockId);
page.addBlock('affine:paragraph', {}, frameId);
// Init editor with the page store
const editor = new EditorContainer();
editor.page = page;
document.body.appendChild(editor);
}
main();For React developers, check out the @blocksuite/react doc for React components and hooks support.
For more detailed planning and progress, please checkout our GitHub project.
- Basic text editing
- ✅ Paragraph with inline style
- ✅ Nested list
- ✅ Code block
- ✅ Markdown shortcuts
- Block-level editing
- ✅ Inline text format bar
- ✅ Inline slash menu
- ✅ Block hub
- ✅ Block drag handle
- ✅ Block-level selection
- Rich-content
- ✅ Image block
- 🚧 Database block
- 📌 Third-party embedded block
- Whiteboard (edgeless mode)
- ✅ Zooming and panning
- ✅ Frame block
- ⚛️ Shape element
- ⚛️ Handwriting element
- 🚧 Grouping
- Playground
- ✅ Multiplayer collaboration
- ✅ Local data persistence
- ✅ E2E test suite
- Developer experience
- ✅ Block tree update API
- ✅ Zero cost time travel (undo/redo)
- ✅ Reusable NPM package
- ✅ React hooks integration
- 📌 Dynamic block registration
Icons above correspond to the following meanings:
- ✅ - Beta
- ⚛️ - Alpha
- 🚧 - Developing
- 📌 - Planned
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.