refactor(extensions): rewrite to use new extension system #2143

nperez0111 · 2025-10-31T14:17:15Z

Summary

This sets up a few things:

A more concretely defined BlockNote Extension API, which now supports:
- A tanstack store instance which defines the public state of an extension, which anything that has access to the editor instance can access
- An init lifecycle method, an extension can be initialized with the current view & be called back when unmounted if it returns a callback function, or listens to it's abortController.
Refactors all of the existing extensions to use the new API system
BlockNote Extensions can be declared at initialization, and added or removed at runtime (by registering or unregistering the extensions)
A useEditorState hook which allows for efficient selection of editor state in a convenient Redux-like API

Rationale

The BlockNote extension API was somewhat haphazardly created out of the need to extend the API for BlockNote for things that an editor naturally needs, such as keyboard shortcuts, input rules, and exposing the ProseMirror plugin API for mroe advanced use cases. We migrated this in piecemeal, supporting ProseMirror Plugins, Tiptap extensions & a stripped down BlockNote extension API, but we need more!
So we've introduced what we feel to be a pretty scalable API, where in an extension can have a lifecycle, added & removed from the editor, expose methods which other parts of the app/UI can call. This gives everything that an extension can need, state to expose, access to the editor instance to register callbacks on, etc.

Changes

This majorly refactors all of the existing built-in extensions to use the new createExtension API, along the way, trying to simplify them to use the minimal state possible & leaving the rest to the UI to actually derive.

Impact

Testing

Screenshots/Video

Checklist

Naming: Extension? Plugin? Settle & rename everything to be consistent. Revisit naming of the getExtension API
[ ]

Additional Notes

Follow ups:

@matthewlipski React-side usage of new plugin signatures
@matthewlipski React floating UI helper hooks (look at useMenuAt.ts for a starting point, it implements the virtual elements to place things within the editor at the correct position).
- useMenuAtPosition( whichPos: (ctx: {editor: BlockNoteEditor }) => { from: number, to?: number }, floatingUIOptions: Object)
- useMenuAtBlock( whichBlock: (ctx: {editor: BlockNoteEditor }) => BlockID, floatingUIOptions: Object) built on previous? Should this just be based on the location API?

vercel · 2025-10-31T14:17:22Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
blocknote	Error		Nov 4, 2025 2:41pm
blocknote-website	Error		Nov 4, 2025 2:41pm

nperez0111 · 2025-11-03T10:09:35Z

packages/core/src/extensions/Collaboration/CursorPlugin.ts

-    });
-    const L = 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
-    return L <= 0.179;
+export const CursorPlugin = createExtension((_editor, options) => {


TODO, there were some defaults here that were being set that may no longer be working

nperez0111 · 2025-11-03T10:13:18Z

packages/core/src/extensions/Collaboration/ForkYDocPlugin.ts

+
+  return {
+    key: "yForkDoc",
+    store,


I'm not entirely certain on this pattern, perhaps we can also allow derived values to be the store?

The point here was to hide the internal state, which should not need to be accessed by anyone other than the plugin.

nperez0111 · 2025-11-03T10:18:05Z

packages/core/src/extensions/Comments/CommentsPlugin.ts

-   * Whether a comment is currently being composed
-   */
-  private pendingComment = false;
+export const CommentsPlugin = createExtension(


Ideally, this would be part of a separate package now. But will leave for now

nperez0111 · 2025-11-03T10:20:44Z

packages/core/src/extensions/FilePanel/FilePanelPlugin.ts

+
+export const FilePanelPlugin = createExtension((editor) => {
+  const store = createStore({
+    blockId: undefined as string | undefined,


I think that the minimal state that a file panel really needs, is the block which it is currently open to. This being a string implies that it is open, and being undefined means that it is closed. To get the position, you can read it from the DOM.

I think we can do scroll updates & mouse events from floating UI, if not let's discuss.

nperez0111 · 2025-11-03T10:24:03Z

packages/core/src/extensions/FormattingToolbar/FormattingToolbarPlugin.ts

+  const store = createStore({
+    show: false,
+    referencePos: null as DOMRect | null,
+  });


This can likely be simplified further. The only state that this plugin really needs is whether it is being shown or not (for programmatic dismissal). Even the reference position should be derive-able from the current editor state. We will likely want a hook which makes it easy to have a menu at wherever the current selection is, and this should store the majority of the state.

nperez0111 · 2025-11-03T10:28:42Z

packages/core/src/extensions/KeyboardShortcuts/KeyboardShortcutsExtension.ts

+          // (this.options.editor.formattingToolbar?.shown ||
+          //   this.options.editor.linkToolbar?.shown ||
+          //   this.options.editor.filePanel?.shown)


Ideally this would not have to be aware of every menu that could be open. I'm not sure if this means that there should be a single "menu" extension which stores the current state of whatever menu is currently active? Or, if these menus should be setting keyboard handlers to capture the Tab key or otherwise not giving this event to the editor.

nperez0111 · 2025-11-03T10:32:44Z

packages/core/src/extensions/Placeholder/PlaceholderPlugin.ts

+  // TODO defaults?
+  const placeholders = options.placeholders;


There were some defaults here that we should also apply

nperez0111 · 2025-11-03T10:34:11Z

packages/core/src/extensions/ShowSelection/ShowSelectionPlugin.ts

+      { enabled: false },
+      {
+        onUpdate() {
+          editor.transact((tr) => tr.setMeta(PLUGIN_KEY, {}));


TODO check this

nperez0111 · 2025-11-03T10:37:15Z

packages/core/src/extensions/SideMenu/SideMenuPlugin.ts

-          this.view = new SideMenuView(editor, editorView, (state) => {
-            this.emit("update", state);
+          view = new SideMenuView(editor, editorView, (state) => {
+            store.setState(state);


TODO, I did not refactor this extension & maybe should have. It was doing a lot so I didn't take the time for it.

Honestly the gist of the state would be that it knows what the currently hovered block is & whether it is open. There is a lot of handling for drag & drop, which could use some refactoring, but maybe later.

For now, if this integration is enough, then maybe we can stick with it, if not I'll help with the refactor here.

nperez0111 · 2025-11-03T10:43:17Z

packages/core/src/extensions/SuggestionMenu/SuggestionPlugin.ts

-
-  private view: SuggestionMenuView<BSchema, I, S> | undefined;
-  private triggerCharacters: string[] = [];
+export const SuggestionMenuPlugin = createExtension((editor) => {


Same as the SideMenuPlugin, did not refactor, but hopefully the shim works.

nperez0111 · 2025-11-03T10:43:56Z

packages/core/src/extensions/TableHandles/TableHandlesPlugin.ts

-> implements PluginView
-{
-  public state?: TableHandlesState<I, S>;
+export class TableHandlesView implements PluginView {


Same as the SideMenuPlugin, shimmed, but unsure if it works

nperez0111 · 2025-11-03T10:48:22Z

packages/core/src/index.ts

 export * from "./extensions-shared/UiElementPosition.js";
 export * from "./extensions/FilePanel/FilePanelPlugin.js";
 export * from "./extensions/FormattingToolbar/FormattingToolbarPlugin.js";
-export * from "./extensions/LinkToolbar/LinkToolbarPlugin.js";
+export * from "./extensions/LinkToolbar/LinkToolbar.js";
 export * from "./extensions/LinkToolbar/protocols.js";
 export * from "./extensions/SideMenu/SideMenuPlugin.js";
 export * from "./extensions/SuggestionMenu/DefaultGridSuggestionItem.js";


Ideally just one export from extensions

nperez0111 · 2025-11-03T10:48:52Z

packages/core/package.json

  },
  "dependencies": {
    "@emoji-mart/data": "^1.2.1",
+    "@handlewithcare/prosemirror-inputrules": "0.1.3",


Pretty nice to be able to add this, allows us to undo an input rule

…State`

…le (excl. `BlockTypeSelect`)

…plugin-system

vercel bot had a problem deploying to Preview – blocknote October 31, 2025 14:18 Failure

vercel bot had a problem deploying to Preview – blocknote October 31, 2025 14:23 Failure

vercel bot had a problem deploying to Preview – blocknote-website October 31, 2025 14:24 Failure

nperez0111 force-pushed the plugin-system branch from 2e2cb06 to f449a1c Compare October 31, 2025 14:26

refactor(extensions): rewrite to use new extension system

b94e7ee

nperez0111 force-pushed the plugin-system branch from f449a1c to b94e7ee Compare October 31, 2025 14:26

vercel bot had a problem deploying to Preview – blocknote-website October 31, 2025 14:27 Failure

vercel bot had a problem deploying to Preview – blocknote October 31, 2025 14:29 Failure

nperez0111 commented Nov 3, 2025

View reviewed changes

chore: minor fixes

916fc8c

vercel bot had a problem deploying to Preview – blocknote-website November 3, 2025 10:51 Failure

nperez0111 commented Nov 3, 2025

View reviewed changes

vercel bot had a problem deploying to Preview – blocknote November 3, 2025 10:52 Failure

matthewlipski and others added 3 commits November 3, 2025 13:33

Refactored almost all formatting toolbar components to use `useEditor…

6a0150c

…State`

Refactored remaining uses of hooks with useEditorState where possib…

06fa6f7

…le (excl. `BlockTypeSelect`)

feat: virtual element hooks

5ffc5a4

vercel bot had a problem deploying to Preview – blocknote November 3, 2025 13:33 Failure

vercel bot had a problem deploying to Preview – blocknote-website November 3, 2025 13:33 Failure

Merge branch 'plugin-system' of github.com:TypeCellOS/BlockNote into …

9b266e5

…plugin-system

vercel bot had a problem deploying to Preview – blocknote-website November 4, 2025 14:41 Failure

vercel bot had a problem deploying to Preview – blocknote November 4, 2025 14:41 Failure

Uh oh!

refactor(extensions): rewrite to use new extension system #2143

Are you sure you want to change the base?

refactor(extensions): rewrite to use new extension system #2143

Uh oh!

Conversation

nperez0111 commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Rationale

Changes

Impact

Testing

Screenshots/Video

Checklist

Additional Notes

Uh oh!

vercel bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nperez0111 commented Oct 31, 2025 •

edited

Loading

vercel bot commented Oct 31, 2025 •

edited

Loading