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 17, 2025 7:55am
blocknote-website	✅ Ready (Inspect)	Visit Preview	Apr 17, 2025 7:55am

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: 91c1d3d

YousefED

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

packages/core/src/api/nodeUtil.ts

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)

I think I've solved it. We just override the Tiptap dispatchTransaction method & re-implement it for ourselves.

I made this into a new event type to not disrupt any callers (even though it only adds a new field to the context). It also makes it clear that we should clean this up when we get off of Tiptap V2.

The switch to v3 then becomes only having to switch which event type to listen for, simple!

06b4306

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!

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

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 :)

I was able to clean this one up & filter out the parent from the change

7ed62d8

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?

isChangeOrigin is never false for transactions emitted by y-sync plugin. So I just removed it.

If you are wondering what it is for, ysync plugin can tell if a change is made within the set of origins that the undo manager is looking for. It stores this in it's state but never sets it to anything other than true on a prosemirror transaction

…de a new `v3-update` method

sentry-io · 2025-04-17T08:51:30Z

Suspect Issues

This pull request was deployed and Sentry observed the following issues:

‼️ InvalidStateError: Failed to execute 'send' on 'WebSocket': Still in CONNECTING state. /docs/collaboration/comments View Issue
‼️ RangeError: Position 5945 outside of fragment (<blockGroup(blockContainer(paragraph))>) / View Issue
‼️ RangeError: Index 1 out of range for <tableParagraph("c")> / View Issue
‼️ RangeError: Index 1 out of range for <tableParagraph("c")> / View Issue
‼️ ShikiError: Language typescriptreact not found, you may need to load it first /examples/theming/custom-code-block View Issue

_{Did you find this useful? React with a 👍 or 👎}

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

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

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

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

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

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

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

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

vercel bot deployed to Preview – blocknote April 10, 2025 16:03 View deployment

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

nperez0111 added 3 commits April 16, 2025 13:40

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

8f88441

test: add tests for the change handler

3a61369

test: add even more tests

47ceeec

nperez0111 added 6 commits April 16, 2025 13:40

test: add tests for nested blocks

a38bcaf

feat: add isChangeOrigin and isUndoRedoOperation to yjs-remote event

69f09f0

test: update tests to use snapshots

0a43978

feat: implement the dispatchTransaction method from Tiptap to provi…

0770464

…de a new `v3-update` method

fix: filter out parent blocks from child changes

079baf4

chore: move to snapshots folder

9d22877

nperez0111 force-pushed the feat/get-changes branch from 7ed62d8 to 9d22877 Compare April 16, 2025 11:42

nperez0111 changed the base branch from feat/blocknote-transactions to main April 16, 2025 11:47

vercel bot had a problem deploying to Preview – blocknote April 16, 2025 12:13 Failure

vercel bot had a problem deploying to Preview – blocknote-website April 16, 2025 12:14 Failure

feat: filter out parent updates

2da36d1

vercel bot deployed to Preview – blocknote April 16, 2025 15:03 View deployment

chore: cleanup event types

31aa9c5

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

vercel bot deployed to Preview – blocknote April 16, 2025 15:35 View deployment

nperez0111 added 2 commits April 17, 2025 09:19

Merge branch 'main' into feat/get-changes

d18db4c

docs: add docs

91c1d3d

vercel bot deployed to Preview – blocknote-website April 17, 2025 07:45 View deployment

nperez0111 merged commit 540dbf8 into main Apr 17, 2025
7 of 8 checks passed

nperez0111 deleted the feat/get-changes branch April 17, 2025 07:53

vercel bot deployed to Preview – blocknote April 17, 2025 07:55 View deployment

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

matthewlipski Apr 9, 2025

nperez0111 Apr 9, 2025 •

edited

Loading

YousefED Apr 10, 2025

nperez0111 Apr 10, 2025 •

edited

Loading

YousefED Apr 10, 2025

nperez0111 Apr 10, 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

nperez0111 Apr 10, 2025 •

edited

Loading

YousefED Apr 10, 2025

nperez0111 Apr 16, 2025

sentry-io bot commented Apr 17, 2025 •

edited

Loading

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

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

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

YousefED left a comment

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

sentry-io bot commented Apr 17, 2025 • edited Loading

Suspect Issues

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

nperez0111 Apr 10, 2025 •

edited

Loading

sentry-io bot commented Apr 17, 2025 •

edited

Loading