BlockSuite: A Web Component Toolkit for Building Block Editors

The problem BlockSuite solves: editors as a toolkit, not a product

Most rich text editors are products. You install them, configure a toolbar, and live inside their document model. BlockSuite takes the opposite position. Its README opens with a line that reads like a manifesto: people who are really serious about editors should make their own framework. The project is a toolkit for building editors and collaborative applications, not an editor you drop into a page.

The audience follows from that. BlockSuite is aimed at teams that need a block-based document model they can extend, and at applications where several views (text, canvas, tables, mind maps) should share one underlying content representation. The README frames this as multimodal editable content: when knowledge is treated as a single source of truth, its various view modes should not each require an incompatible framework.

The project grew out of AFFiNE, the knowledge base, and was open sourced and maintained independently once it became clear it was outgrowing its role as an in-house editor. That origin explains both its strengths and its rough edges: it carries the requirements of a real product, but it is published as infrastructure.

How BlockSuite works: a headless framework plus prebuilt editor components

The repository is organized into two groups of packages: a headless framework under packages/framework, and prebuilt editing components. The framework is where the document model, commands and synchronization live. The components are the editors you actually render.

Everything is a native web component. The README states this explicitly for all BlockSuite components, including the editors, and calls out the consequence: they are framework-agnostic and easy to interop with React or other frameworks. This is the sharpest architectural difference from AFFiNE, which uses React. The README compares the relationship to Monaco Editor and VSCode, but notes one difference: BlockSuite is not generated from the AFFiNE codebase and uses a different tech stack.

Two editors ship as first-party components. PageEditor is a block-based document editor. EdgelessEditor is a graphics editor with opt-in canvas rendering that shares the same rich-text capabilities as PageEditor. Underneath, the framework supports custom blocks and inline embeds, incremental updates, and a command mechanism the README describes as similar to React hooks but designed for document editing. Collaboration is not bolted on: the README says the underlying CRDT technology is used for editor state management, and links to a blog post on a CRDT-native data flow. Document streaming, snapshots and transformers handle synchronization and persistence, including markdown and HTML compatibility.

Installing BlockSuite and rendering a first editor

The README does not spell out install commands in the text shown here. It points to the quick start guide at blocksuite.io/guide/quick-start.html and says to start with the preset editors in @blocksuite/presets. The repository's own development scripts assume Yarn 4.7.0 and Node between 18.19.0 and 23.0.0, per the root package.json engines field.

If you are working inside the repository rather than consuming the published packages, the root scripts are the entry point. This starts the playground workspace, which is the fastest way to see the editors without writing an application:

yarn install
yarn dev

The playground is defined as @blocksuite/playground in the workspaces list, and the dev script proxies to yarn workspace @blocksuite/playground dev. For a production build of the published packages, the root exposes a separate script:

yarn build:packages

That script runs yarn workspace @blocksuite/affine build, which is the package the publish step builds before pushing to npm. Note the two npm tags in the root scripts: ci:publish uses --tag latest, while ci:publish:canary uses --tag canary. If you install from npm, be deliberate about which tag you resolve, because the repository maintains both.

What the early-stage warning actually costs you

The README carries a warning: BlockSuite is currently in its early stage, with components and extension capabilities still under refinement. That sentence should shape how you read everything else on this page. It means the extension surface is the part most likely to move under you.

The release cadence supports a careful reading. The most recent release listed is v0.22.4 on 2025-07-01, preceded by v0.21.0 on 2025-04-07 and v0.19.5 on 2024-12-19. The version numbers are still in the 0.x range, and the gaps between minor releases are measured in months. The repository itself was last pushed on 2026-09-15, so work continues, but a 0.x version line with multi-month minor releases is not a stability guarantee.

The practical failure mode is not that the editor breaks. It is that the guide you follow and the package you install drift apart. A tutorial written against one minor version may reference command or block APIs that changed in the next. The README's own framing, that components and extension capabilities are under refinement, tells you to pin versions and read the changelog rather than assume backwards compatibility. If you need a frozen extension API with a long deprecation window, this is the wrong tool today.

BlockSuite compared with Tiptap and other editor frameworks

Tiptap is the comparison people reach for, and the difference is structural rather than cosmetic. Tiptap is built around ProseMirror's document model and is typically consumed as a set of extensions inside a host framework such as React or Vue. You compose an editor from extensions, and collaboration is added through a separate provider.

BlockSuite inverts several of those choices. Its components are web components, so the host framework is not the integration point. Its editors are prebuilt rather than assembled from primitives, with PageEditor and EdgelessEditor offered as first-party components you can reuse or extend. And collaboration is native to the state layer: the README describes using CRDT technology for editor state management rather than treating real-time collaboration as an optional plugin. The project also manages state across multiple documents, which the README lists as a design goal for handling intertwined references.

That makes BlockSuite a heavier commitment and a different kind of dependency. Choosing Tiptap means adopting an extension ecosystem around ProseMirror. Choosing BlockSuite means adopting a document model, a command system and a component layer that were designed together, with the trade-off that the layer is younger and less documented.

Licence and upgrade cost

BlockSuite is licensed under MPL-2.0, as stated in the root package.json and the repository's LICENSE file. MPL-2.0 is a file-level copyleft licence: modifications to covered files carry source-disclosure obligations, while larger works that combine it with other code are treated differently from a project-wide copyleft. This is a description of the licence identifier, not legal advice. If you plan to modify BlockSuite files and ship the result, have counsel review your specific distribution model.

Upgrade cost is driven by the 0.x version line. The repository uses Changesets for versioning, with ci:version and ci:version:canary scripts, and a changeset script that runs a changelog generator. That means release notes exist and are generated per change, which is the mechanism you would rely on when moving between minor versions. The absence of a stable major version is the real cost: budget for reading changelogs on each bump rather than assuming drop-in upgrades, and pin the exact version in your lockfile.

Editorial conclusion

Adopt BlockSuite when you need a block editor with CRDT-native collaboration and you are comfortable with web components and a framework the README itself calls early stage. Do not adopt it if you need a stable, documented extension API today, or if you want a batteries-included editor you never touch internally. Before committing, verify that the @blocksuite/presets package you install matches the version of the guide you are reading, and confirm which npm tag your build resolves to, since the repository publishes both latest and canary releases.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. Project website
3. README
4. Releases
5. toeverything/blocksuite on GitHub