@blocksuite/store

@blocksuite/store is the data layer of BlockSuite, the content-editing tech stack behind AFFiNE. It provides a general-purpose, CRDT-backed state store built on Yjs, modeling documents as trees of typed blocks with a schema system, reactive proxies, and serialization adapters so multiple users can edit the same document concurrently without conflicts.

Rather than a full editor, this package is the foundation you build one on: it handles block models, undo/redo, reactive text and object data, transformers for import/export, and awareness for presence. It is the most widely installed BlockSuite package and is designed to be framework-agnostic so it can back editors written with any UI layer.

What You Get

• A CRDT-backed document store built on Yjs with automatic conflict resolution
• A block schema system and typed block models with a reactive proxy layer
• Transformers and adapters for serializing documents to and from other formats
• Awareness and sync primitives for real-time presence and multi-user collaboration

Common Use Cases

• Building a collaborative block-based document or whiteboard editor
• Adding conflict-free real-time editing to an existing rich-text application
• Persisting and syncing structured document state across clients via Yjs

Under The Hood

Architecture - Living at packages/framework/store in the BlockSuite monorepo, the package’s src/index.ts re-exports layered modules: model/ (block and store containers), schema/ (block schema validation), reactive/ (proxy, boxed values, and reactive text built on @preact/signals-core), yjs/ (the Yjs document, awareness, and utilities), transformer/ and adapter/ (import/export and serialization), and an id generator. Documents are represented as trees of typed blocks whose state lives in a shared Yjs CRDT, so concurrent edits merge deterministically while the reactive layer surfaces changes to consumers.

Tech Stack - Written in TypeScript and consumed directly from source via package exports. It builds on yjs and y-protocols for CRDT and awareness, lib0 for low-level utilities, @preact/signals-core and rxjs for reactivity, zod for schema validation, nanoid for ids, and several lodash helpers, alongside the sibling @blocksuite/global and @blocksuite/sync packages.

Code Quality - The store is well tested with Vitest unit specs under src/__tests__ covering blocks, collections, docs, schema, transformers, and Yjs behavior, plus snapshot fixtures. The code is strictly typed and modular, and even guards against being imported twice to avoid the Yjs constructor-identity pitfall, reflecting a mature, production-grade codebase that backs the AFFiNE app.

API Design - The public API is broad because it spans models, schemas, reactivity, and serialization, which gives it real power but a steeper learning curve than a single-purpose utility. Naming is consistent and domain-oriented (blocks, docs, collections, transformers), and comprehensive documentation at blocksuite.io helps offset the conceptual load of learning the CRDT-based data model.