@blocknote/core

@blocknote/core is the framework-agnostic engine behind BlockNote, an open-source “Notion-style” block-based rich text editor. Instead of exposing raw ProseMirror nodes and marks, it models every piece of content as a typed Block with an id, type, props, content, and nested children, giving consumers drag-and-drop reordering, indentation/nesting, and slash-menu-driven block insertion without hand-building those primitives themselves.

Under the hood it wraps Tiptap and ProseMirror directly (prosemirror-model, prosemirror-state, prosemirror-transform, prosemirror-view, prosemirror-tables) and layers real-time collaboration on top via optional Yjs integration (yjs, y-prosemirror, y-protocols, plus the newer @y/* packages). It ships default blocks (paragraphs, headings, lists, tables, images, video, audio, files, code blocks) and exporters to/from HTML and Markdown, while React bindings, theming, and AI features live in sibling packages (@blocknote/react, @blocknote/mantine, @blocknote/shadcn, @blocknote/xl-ai) that build on this core.

What You Get

• A BlockNoteEditor class with a typed public API for creating, reading, and mutating block-structured documents
• A default block schema (paragraph, heading, list, table, image, video, audio, file, code block) plus a BlockNoteSchema API for defining fully custom block, inline-content, and style types
• Built-in exporters and parsers for converting between BlockNote’s block model and HTML or Markdown
• Optional real-time collaboration support via Yjs, wired through dedicated y/ and yjs/ modules
• An extension system (BlockNoteExtension/ExtensionFactory) for composing editor behavior such as drag cursors, unique IDs, and paste handling
• Internationalization support through a Dictionary type and bundled locale files

Common Use Cases

• Embedding a Notion-style block editor into a React or web application as the content-authoring surface
• Building collaborative document editors where multiple users edit the same content in real time via Yjs
• Exporting user-authored block content to HTML or Markdown for storage, publishing, or further processing
• Defining a custom block schema (e.g. embeds, callouts, or domain-specific blocks) for a tailored editing experience
• Powering CMS or knowledge-base editing UIs that need structured, block-level content instead of a single HTML blob

Under The Hood

Architecture The BlockNoteEditor class (src/editor/BlockNoteEditor.ts, ~1,400 lines) is the central façade, instantiated via BlockNoteEditor.create(), composing an underlying Tiptap Editor instance and delegating specialized concerns to dedicated manager classes — BlockManager, EventManager, ExportManager, ExtensionManager, SelectionManager, StateManager, and StyleManager (src/editor/managers/) — a composition-over-inheritance layering that keeps ProseMirror/Tiptap primitives wrapped behind block and inline-content abstractions defined in src/schema and src/blocks. The generically-typed BlockNoteSchema (src/blocks/BlockNoteSchema.ts) threads BSchema/ISchema/SSchema type parameters through the editor, block conversions, and exporters, so a change to the block-schema shape ripples through the whole conversion pipeline. Collaboration is layered in via separate y/ and yjs/ directories bridging to Yjs CRDTs without leaking into core editor logic, and features are composed through an Extension/ExtensionFactory pattern rather than hardcoded into the editor.

Tech Stack Written entirely in TypeScript, the package depends directly on @tiptap/core and several ProseMirror packages (prosemirror-model, prosemirror-state, prosemirror-transform, prosemirror-view, prosemirror-tables), layering a block-based document model on top of Tiptap’s node-based one. Real-time collaboration integrates through yjs, y-prosemirror, and y-protocols (declared as optional peer dependencies), alongside newer @y/* packages for an updated Yjs API. The monorepo (19 packages under packages/) is built and tested with a custom Vite-based task runner (“vite-plus”), tests run under Vitest with a jsdom environment, and the package intentionally carries no UI framework dependency — React bindings, theming, and AI features live in sibling packages that build on this core.

Code Quality The package includes around 60 test files covering the block schema, content-type propagation, Yjs utilities, user store, and topological sort logic, run via Vitest. Error handling favors explicit invariants over silent fallthrough — UnreachableCaseError and assertEmpty helpers in util/typescript.ts catch invalid branches at compile and runtime — and the public API is extensively JSDoc-documented throughout BlockNoteEditor.ts, with generic type parameters enforcing compile-time safety for consumers extending the schema. Naming is consistent across the codebase, file layout mirrors domain concepts (blocks/, schema/, editor/managers/), and CI runs type-aware linting plus a dedicated end-to-end test workflow.

What Makes It Unique Where most rich text editor libraries (Tiptap, Slate) expose a node/mark-centric ProseMirror-style API directly, BlockNote’s differentiator is treating the block as the first-class unit of content, giving drag-and-drop reordering, nesting, and Notion-style slash-menu interactions out of the box rather than requiring consumers to build those primitives themselves on raw ProseMirror. Combined with built-in real-time collaboration, multi-column layouts, comments, and (via sibling xl-* packages) AI-assisted editing and document export, it positions itself less as a bare rich text toolkit and more as a batteries-included block-editor platform.