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, using BlockSuite does not require working with data-driven DSLs (e.g., operations, actions, commmands, transforms...). Instead, by using CRDT as the single source of truth, BlockSuite provides a strongly-typed block tree model based on Yjs. In BlockSuite, manipulating blocks is as easy as updating a todo list. Meanwhile, by taking full advantage of CRDT, it supports zero-cost time travel, real-time collaboration, and pluggable persistence backends right out of the box.
- For rich text editing, BlockSuite orchestrates rich text content into discrete blocks. In BlockSuite, a document with 100 paragraphs can be rendered into 100 text blocks, aka 100 rich text editor instances, eliminating the classic practice of putting all content into one dangerous
contenteditale
monolith. - At the rendering layer, BlockSuite is framework agnostic. It does not assume that the block tree can only be rendered through the DOM. It not only implements its entire document editing UI based on Web Components, but also provides a hybrid canvas-based renderer for parts of the whiteboard content. Both renderers can coexist on the same page and share the same 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@nightly
If 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/store
package is a data store built for general-purpose state management. - The
packages/blocks
package holds the default BlockSuite editable blocks. - The
packages/editor
package ships a complete BlockSuite-based editor.
pnpm i \
@blocksuite/store@nightly \
@blocksuite/blocks@nightly \
@blocksuite/editor@nightly
And 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
,Block
andSlot
. These are the primitives for building a block-based collaborative application. We are preparing a comprehensive documentation about their usage!
import '@blocksuite/blocks';
// A workspace can hold multiple pages, and a page can hold multiple blocks.
import { Workspace, Page } from '@blocksuite/store';
import { builtInSchemas } from '@blocksuite/blocks/models';
import { EditorContainer } from '@blocksuite/editor';
/**
* Manually create the initial page structure.
* In collaboration mode or on page refresh with local persistence,
* the page data will be automatically loaded from store providers.
* In these cases, this function should not be called.
*/
function createInitialPage(workspace: Workspace) {
// Events are being emitted using slots.
workspace.slots.pageAdded.once(pageId => {
const page = workspace.getPage(pageId) as Page;
// Block types are defined and registered in BlockSchema.
const pageBlockId = page.addBlock({ flavour: 'affine:page' });
const frameId = page.addBlock({ flavour: 'affine:frame' }, pageBlockId);
page.addBlock({ flavour: 'affine:paragraph' }, frameId);
});
// Create a new page. This will trigger the slot above.
workspace.createPage('page0');
}
// Subscribe for page update and create editor on page added.
function initEditorOnPageAdded(workspace: Workspace) {
workspace.slots.pageAdded.once(pageId => {
const page = workspace.getPage(pageId) as Page;
const editor = new EditorContainer();
editor.page = page;
document.body.appendChild(editor);
});
}
function main() {
// Initialize the store.
const workspace = new Workspace({ id: 'test' }).register(builtInSchemas);
// Start waiting for the first page...
initEditorOnPageAdded(workspace);
// Suppose we are the first one to create the page.
createInitialPage(workspace);
}
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.