feat: `change` event allows getting a list of the changes made #1585

nperez0111 · 2025-04-04T12:43:42Z

This implements a getChanges API which will derive the changes made within a transaction as a list of: inserts, updates and deletions of blocknote blocks

To test this you can update an example like so:

diff --git i/examples/01-basic/01-minimal/App.tsx w/examples/01-basic/01-minimal/App.tsx
index a3b92bafd..d5c43ac2b 100644
--- i/examples/01-basic/01-minimal/App.tsx
+++ w/examples/01-basic/01-minimal/App.tsx
@@ -8,5 +8,12 @@ export default function App() {
   const editor = useCreateBlockNote();
 
   // Renders the editor instance using a React component.
-  return <BlockNoteView editor={editor} />;
+  return (
+    <BlockNoteView
+      editor={editor}
+      onChange={(t, ctx) => {
+        console.log("changes", ctx.getChanges());
+      }}
+    />
+  );
 }

Things left:

add tests

Resolves #1541 #482 #1566

vercel · 2025-04-04T12:43:45Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
blocknote	✅ Ready (Inspect)	Visit Preview	Apr 9, 2025 2:06pm
blocknote-website	✅ Ready (Inspect)	Visit Preview	Apr 9, 2025 2:06pm

Copilot

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

pkg-pr-new · 2025-04-07T07:50:40Z

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/ariakit@1585

@blocknote/code-block

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/code-block@1585

@blocknote/core

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/core@1585

@blocknote/mantine

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/mantine@1585

@blocknote/react

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/react@1585

@blocknote/server-util

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/server-util@1585

@blocknote/shadcn

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/shadcn@1585

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-docx-exporter@1585

@blocknote/xl-multi-column

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-multi-column@1585

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-odt-exporter@1585

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-pdf-exporter@1585

commit: 56e079b

YousefED

this is so awesome, and implementation actually cleaner / clearer than expected! really cool

YousefED · 2025-04-07T17:59:29Z

packages/core/src/api/nodeUtil.ts

+  } else if (transaction.getMeta("uiEvent") === "drop") {
+    source = { type: "drop" };
+  } else if (transaction.getMeta("history$")) {
+    source = {


does this work for collaboration as well (yjs history)?

This works only for the history plugin. But, I think y-prosemirror tells us if an undo happened (unsure if locally or remote or both), so maybe I can do it for that too

YousefED · 2025-04-07T18:06:22Z

packages/core/src/api/nodeUtil.ts

+  const changes: BlocksChanged<BSchema, ISchema, SSchema> = [];
+  // TODO when we upgrade to Tiptap v3, we can get the appendedTransactions which would give us things like the actual inserted Block IDs.
+  // since they are appended to the transaction via the unique-id plugin
+  const combinedTransaction = combineTransactionSteps(transaction.before, [


I don't completely understand this. How do we get the block ids now then, if we don't yet support the uniqueid transactions?

Tiptap V2 gives the root tr that was applied which does not include any appended transactions (since it is only the root tr).
Tiptap V3 gives both root tr & any appended transaction in that callback which means you can see the appended transactions & re-combine them to get the "actual" changed ranges.

Technically, the editor state is up to date by the time we are reading this, but we can't know what transactions have been appended so our transaction ranges can be incorrect.

The reason that we are getting ids out of this right now is that nodeToBlock will generate an ID if it does not find one. But, those IDs are not the same ID that actually would have been persisted into the document.

What do we actually need to need the UniqueId transactions for? Since this is more for tracking user changes, so giving a new block an ID doesn't seem like smth we need to listen for. So is the issue just that if a new block is created, when we try to get it with nodeToBlock, it will generate a random ID as the UniqueId transaction is not detected here?

The reason the unique-id appended transaction is important is that if you do getChanges, any inserted block technically hasn't been assigned an ID yet, it just generates one at random (in nodeToBlock as you described). So, you can't actually trust that ID to do lookups anywhere (in the document or otherwise). So, in the future, we can actually append that transaction to get the correct ID and not have that issue - making the ID reported by getChanges accurate to what is actually in the document.

The reason that we are getting ids out of this right now is that nodeToBlock will generate an ID if it does not find one. But, those IDs are not the same ID that actually would have been persisted into the document.

is this a blocker for the PR? it makes the "insert" changes not very useful then, right?

It depends on what they are using this for. If this is just to inspect the content to do things like remove image uploads, then it won't matter.

I'm uncertain of what you'd need the insert changes for, much less whether it is a hard requirement to have the ID be correct. I get that correctness is important, in general. But, I hope that Tiptap V3 is around the corner and alleviates us of this.

Thinking out loud: One way to get around this would be to get the previous editor state & apply the transaction again (which would run the plugins again). But, the ID would still be incorrect since it was randomly generated. So, not helpful either.
Another way would be to try to find the node afterward, but technically any plugin could append a transaction that makes the position no longer valid. So not helpful in the general case, but probably fine just for blocknote.
Or, on inserting a node, we just already give it an ID

Hmm, those workarounds sound painful. I figured a quick and easy fix be to update insertBlocks to add the id before issueing the transaction. However, then we'd still have scenarios where user operations like enter doesn't show the right id

It depends on what they are using this for. If this is just to inspect the content to do things like remove image uploads, then it won't matter.

Thinking of two scenarios atm that will be difficult now:

Table of contents: detect inserted headings and turn them into a ToC. While this would now work, you can't make clicking the ToC heading work because you don't know to which block in the document you need to scroll

post-processing: maybe you'd want to use this API to do some kind of post-processing / validation and update the block to make sure it always satisfies "some" requirements - (ofc; doing this after a change is still rather hacky; we should probably know more about these use-cases and expose a better API for this)

YousefED · 2025-04-07T18:10:07Z

packages/core/src/api/nodeUtil.test.ts

+  let originalDispatch: typeof editor.dispatch;
+
+  beforeEach(() => {
+    transaction = undefined as unknown as Transaction;


not easier to test the onchange event directly instead of patching like this?

Likely easier, but the test is not for the change event, but to see if a transaction can give us the changes. I'd want it isolated

packages/core/src/api/nodeUtil.test.ts

matthewlipski · 2025-04-09T09:42:15Z

packages/core/src/api/nodeUtil.ts

+  const changes: BlocksChanged<BSchema, ISchema, SSchema> = [];
+  // TODO when we upgrade to Tiptap v3, we can get the appendedTransactions which would give us things like the actual inserted Block IDs.
+  // since they are appended to the transaction via the unique-id plugin
+  const combinedTransaction = combineTransactionSteps(transaction.before, [


What do we actually need to need the UniqueId transactions for? Since this is more for tracking user changes, so giving a new block an ID doesn't seem like smth we need to listen for. So is the issue just that if a new block is created, when we try to get it with nodeToBlock, it will generate a random ID as the UniqueId transaction is not detected here?

matthewlipski · 2025-04-09T09:44:21Z

packages/core/src/api/nodeUtil.ts

+  removedBlockIds.forEach((blockId) => {
+    changes.push({
+      type: "delete",
+      block: prevAffectedBlocks.find((block) => block.id === blockId)!,


Shouldn't prevBlock be set instead of block? Since the block previously existed and no longer does

I thought of doing that too. But felt that if someone just wanted, "list of all changed blocks", it'd be just getChanges().map(c=>c.block), whereas branching on the type is more cumbersome.

I think an argument can be made for either way (i.e. the type is 'deleted' so obviously block is the deleted block)

Yep fair, I don't have a strong opinion one way or another, just wanted to make sure it was intentional

examples/07-collaboration/01-partykit/App.tsx

packages/core/src/api/nodeUtil.test.ts

YousefED

small last notes added!

YousefED · 2025-04-10T09:12:20Z

packages/core/src/api/blocks-deleted-nested.json

+    },
+    "type": "delete",
+  },
+  {


Q: do we want to show parent as an "update" to the consumer? can we clearly explain this?

YousefED · 2025-04-10T09:13:34Z

packages/core/src/api/blocks-updated-nested.json

@@ -0,0 +1,190 @@
+[
+  {


this is the case we discussed. The we want it like this (can we clearly explain this), or prefer only to share the update children?

Let's at least make sure it's clearly documented :)

YousefED · 2025-04-10T09:14:14Z

packages/core/src/api/nodeUtil.ts

+      /**
+       * Whether the change is from this client or another client.
+       */
+      isChangeOrigin: boolean;


if this is false, shouldn't we just trigger type: "local" instead?

vercel bot deployed to Preview – blocknote-website April 4, 2025 13:05 View deployment

nperez0111 requested review from matthewlipski and Copilot April 4, 2025 13:07

Copilot AI reviewed Apr 4, 2025

View reviewed changes

vercel bot deployed to Preview – blocknote April 4, 2025 13:16 View deployment

nperez0111 force-pushed the feat/blocknote-transactions branch from 4ce1f42 to 4a3d364 Compare April 7, 2025 07:45

feat: change event allows getting a list of the changes made

96b242b

nperez0111 force-pushed the feat/get-changes branch from 24382b7 to 96b242b Compare April 7, 2025 07:46

vercel bot deployed to Preview – blocknote April 7, 2025 08:18 View deployment

vercel bot deployed to Preview – blocknote-website April 7, 2025 08:29 View deployment

nperez0111 requested a review from YousefED April 7, 2025 08:32

nperez0111 added 2 commits April 7, 2025 10:53

test: add tests for the change handler

fcdc99c

test: add even more tests

8948cf5

vercel bot deployed to Preview – blocknote-website April 7, 2025 09:25 View deployment

vercel bot deployed to Preview – blocknote April 7, 2025 09:36 View deployment

YousefED reviewed Apr 7, 2025

View reviewed changes

test: add tests for nested blocks

5132e66

vercel bot deployed to Preview – blocknote-website April 8, 2025 10:04 View deployment

vercel bot deployed to Preview – blocknote April 8, 2025 10:15 View deployment

feat: add isChangeOrigin and isUndoRedoOperation to yjs-remote event

4f5325f

vercel bot deployed to Preview – blocknote-website April 8, 2025 11:38 View deployment

vercel bot deployed to Preview – blocknote April 8, 2025 11:50 View deployment

matthewlipski reviewed Apr 9, 2025

View reviewed changes

test: update tests to use snapshots

56e079b

vercel bot deployed to Preview – blocknote April 9, 2025 13:58 View deployment

vercel bot deployed to Preview – blocknote-website April 9, 2025 14:06 View deployment

YousefED reviewed Apr 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: `change` event allows getting a list of the changes made #1585

feat: `change` event allows getting a list of the changes made #1585

nperez0111 commented Apr 4, 2025 •

edited

Loading

vercel bot commented Apr 4, 2025 •

edited

Loading

Copilot AI left a comment

pkg-pr-new bot commented Apr 7, 2025 •

edited

Loading

YousefED left a comment

YousefED Apr 7, 2025

nperez0111 Apr 8, 2025

YousefED Apr 7, 2025

nperez0111 Apr 8, 2025

matthewlipski Apr 9, 2025

nperez0111 Apr 9, 2025 •

edited

Loading

YousefED Apr 10, 2025

nperez0111 Apr 10, 2025 •

edited

Loading

YousefED Apr 10, 2025

YousefED Apr 7, 2025

nperez0111 Apr 8, 2025

matthewlipski Apr 9, 2025

matthewlipski Apr 9, 2025

nperez0111 Apr 9, 2025

matthewlipski Apr 9, 2025

YousefED left a comment

YousefED Apr 10, 2025

YousefED Apr 10, 2025

YousefED Apr 10, 2025

feat: change event allows getting a list of the changes made #1585

Are you sure you want to change the base?

feat: change event allows getting a list of the changes made #1585

Conversation

nperez0111 commented Apr 4, 2025 • edited Loading

vercel bot commented Apr 4, 2025 • edited Loading

Copilot AI left a comment

Choose a reason for hiding this comment

pkg-pr-new bot commented Apr 7, 2025 • edited Loading

YousefED left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nperez0111 Apr 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nperez0111 Apr 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

YousefED left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feat: `change` event allows getting a list of the changes made #1585

feat: `change` event allows getting a list of the changes made #1585

nperez0111 commented Apr 4, 2025 •

edited

Loading

vercel bot commented Apr 4, 2025 •

edited

Loading

pkg-pr-new bot commented Apr 7, 2025 •

edited

Loading

nperez0111 Apr 9, 2025 •

edited

Loading

nperez0111 Apr 10, 2025 •

edited

Loading