Migrate from TipTap extensions to BlockNote native extensions

BlockNote core team confirmed _tiptapOptions will be removed in a
future version. Convert both editor extensions (ExternalLinkCapture,
ExternalLinkA11y) from TipTap Extension.create() to BlockNote
createExtension(), and register via the extensions option instead
of _tiptapOptions.extensions. ProseMirror plugin code is unchanged.

Author: akabiru

frontend/src/react/components/OpBlockNoteEditor.tsx

@@ -105,12 +105,10 @@ export function OpBlockNoteEditor({
       },
       dictionary: localeDictionary,
       ...(attachmentsEnabled && { uploadFile }),
-      _tiptapOptions: {
-        extensions: [
-          ExternalLinkA11yExtension,
-          ...(captureExternalLinks ? [ExternalLinkCaptureExtension] : []),
-        ],
-      },
+      extensions: [
+        ExternalLinkA11yExtension,
+        ...(captureExternalLinks ? [ExternalLinkCaptureExtension] : []),
+      ],
     };
   }, [hocuspocusProvider, doc, activeUser, localeDictionary, attachmentsEnabled, uploadFile, captureExternalLinks]);
 

frontend/src/react/extensions/external-link-a11y.ts

@@ -26,10 +26,10 @@
 // See COPYRIGHT and LICENSE files for more details.
 //++
 
-import { Extension } from '@tiptap/core';
-import { Plugin, PluginKey } from '@tiptap/pm/state';
-import { Decoration, DecorationSet } from '@tiptap/pm/view';
-import type { Node as PmNode } from '@tiptap/pm/model';
+import { createExtension } from '@blocknote/core';
+import { Plugin, PluginKey } from 'prosemirror-state';
+import { Decoration, DecorationSet } from 'prosemirror-view';
+import type { Node as PmNode } from 'prosemirror-model';
 import { isHrefExternal } from 'core-stimulus/helpers/external-link-helpers';
 
 const pluginKey = new PluginKey('externalLinkA11y');
@@ -68,30 +68,28 @@ function buildDecorations(doc:PmNode):DecorationSet {
  * opens in a new tab. It lives in the main layout (`base.html.erb`) and is
  * cloned into the BlockNote shadow DOM by `block-note-element.ts`.
  */
-export const ExternalLinkA11yExtension = Extension.create({
-  name: 'externalLinkA11y',
+export const ExternalLinkA11yExtension = createExtension({
+  key: 'externalLinkA11y',
 
-  addProseMirrorPlugins() {
-    return [
-      new Plugin({
-        key: pluginKey,
-        state: {
-          init(_, { doc }) {
-            return buildDecorations(doc);
-          },
-          apply(tr, oldDecos) {
-            if (tr.docChanged) {
-              return buildDecorations(tr.doc);
-            }
-            return oldDecos.map(tr.mapping, tr.doc);
-          },
+  prosemirrorPlugins: [
+    new Plugin({
+      key: pluginKey,
+      state: {
+        init(_, { doc }) {
+          return buildDecorations(doc);
         },
-        props: {
-          decorations(state) {
-            return pluginKey.getState(state) as DecorationSet;
-          },
+        apply(tr, oldDecos) {
+          if (tr.docChanged) {
+            return buildDecorations(tr.doc);
+          }
+          return oldDecos.map(tr.mapping, tr.doc);
         },
-      }),
-    ];
-  },
+      },
+      props: {
+        decorations(state) {
+          return pluginKey.getState(state) as DecorationSet;
+        },
+      },
+    }),
+  ],
 });

frontend/src/react/extensions/external-link-capture.ts

@@ -26,8 +26,8 @@
 // See COPYRIGHT and LICENSE files for more details.
 //++
 
-import { Extension } from '@tiptap/core';
-import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { createExtension } from '@blocknote/core';
+import { Plugin, PluginKey } from 'prosemirror-state';
 import { buildExternalRedirectUrl, isExternalLinkCandidate, isLinkExternal } from 'core-stimulus/helpers/external-link-helpers';
 
 /**
@@ -44,38 +44,36 @@ import { buildExternalRedirectUrl, isExternalLinkCandidate, isLinkExternal } fro
  * enabled — when disabled, TipTap's default `openOnClick: true` handles
  * link clicks natively.
  */
-export const ExternalLinkCaptureExtension = Extension.create({
-  name: 'externalLinkCapture',
+export const ExternalLinkCaptureExtension = createExtension({
+  key: 'externalLinkCapture',
 
-  addProseMirrorPlugins() {
-    return [
-      new Plugin({
-        key: new PluginKey('externalLinkCapture'),
-        props: {
-          handleDOMEvents: {
-            mousedown: (view, event) => {
-              // Left-click (0) and middle-click (1) only — right-click (2)
-              // opens the native context menu which reads href from the DOM
-              // and cannot be intercepted via JavaScript.
-              if (event.button !== 0 && event.button !== 1) return false;
+  prosemirrorPlugins: [
+    new Plugin({
+      key: new PluginKey('externalLinkCapture'),
+      props: {
+        handleDOMEvents: {
+          mousedown: (view, event) => {
+            // Left-click (0) and middle-click (1) only — right-click (2)
+            // opens the native context menu which reads href from the DOM
+            // and cannot be intercepted via JavaScript.
+            if (event.button !== 0 && event.button !== 1) return false;
 
-              const target = event.target instanceof Element
-                ? event.target
-                : (event.target as Node)?.parentElement;
-              const link = target?.closest('a');
-              if (!(link instanceof HTMLAnchorElement)) return false;
-              if (!view.dom.contains(link)) return false;
-              if (!isExternalLinkCandidate(link)) return false;
-              if (!isLinkExternal(link)) return false;
-              if (link.dataset.allowExternalLink) return false;
+            const target = event.target instanceof Element
+              ? event.target
+              : (event.target as Node)?.parentElement;
+            const link = target?.closest('a');
+            if (!(link instanceof HTMLAnchorElement)) return false;
+            if (!view.dom.contains(link)) return false;
+            if (!isExternalLinkCandidate(link)) return false;
+            if (!isLinkExternal(link)) return false;
+            if (link.dataset.allowExternalLink) return false;
 
-              event.preventDefault();
-              window.open(buildExternalRedirectUrl(link.href), '_blank', 'noopener,noreferrer');
-              return true;
-            },
+            event.preventDefault();
+            window.open(buildExternalRedirectUrl(link.href), '_blank', 'noopener,noreferrer');
+            return true;
           },
         },
-      }),
-    ];
-  },
+      },
+    }),
+  ],
 });