refactor: blocknote API uses lowest possible level prosemirror primitives

[nperez0111]

This refactors all of the blocknote APIs to use low-level prosemirror APIs rather than passing around editor instances and dispatching transactions themselves.
Now, block manipulation functions will only update the current transaction it was provided rather than trying to dispatch it. This allows these commands to be chained without having to resort to any smarts for the transaction handling.

supercedes: #1147 #1604 #1584

Resolves: #829

[vercel]

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

Name	Status	Preview	Updated (UTC)
blocknote	✅ Ready (Inspect)	Visit Preview	Apr 16, 2025 11:50am
blocknote-website	✅ Ready (Inspect)	Visit Preview	Apr 16, 2025 11:50am

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

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

@blocknote/code-block

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

@blocknote/core

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

@blocknote/mantine

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

@blocknote/server-util

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

@blocknote/react

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

@blocknote/shadcn

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

@blocknote/xl-docx-exporter

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

@blocknote/xl-multi-column

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

@blocknote/xl-odt-exporter

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

@blocknote/xl-pdf-exporter

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

commit: 6e6c5fd

[YousefED]

Cool! Do you think you have a preference after these explorations? Specifically looking at which codebase / architecture would be the most maintainable / strongest to work with down the line?

[YousefED]

why are some of the methods like this one wrapped in transact?

[nperez0111]

transact is convenient in that you don't have to create a transaction & then dispatch it. It also is clear that it would work within a blocknote transaction.

If everything were to use this pattern, then you wouldn't even need to have editor.transaction hold the activeTransaction state, it would just be passed around through the transact calls. So, it ends up mapping more closely to what actually happens

[YousefED]

Ah that makes sense! I was looking at it from the angle of "only call transact if you're doing multiple BlockNote API calls in a method.

But you're right, we could also use it for convenience + make the methods consistent. I suppose in that case we need to do it for all usages of dispatch, and perhaps even make dispatch private?

[nperez0111]

Good call on standardizing it, will refactor to that pattern. I think it will come out nice

[nperez0111]

Cool! Do you think you have a preference after these explorations? Specifically looking at which codebase / architecture would be the most maintainable / strongest to work with down the line?

I prefer the explicitness of what we have here, but I think the tradeoff that it makes are methods that need to take a ton of arguments, which is a code smell imo.

Take a look at this method:

BlockNote/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts

Lines 67 to 78 in 34ebafa

	const updateBlockTr = <
	BSchema extends BlockSchema,
	I extends InlineContentSchema,
	S extends StyleSchema
	>(
	tr: Transaction,
	pmSchema: Schema,
	schema: BlockNoteSchema<BSchema, I, S>,
	posBeforeBlock: number,
	block: PartialBlock<BSchema, I, S>,
	blockCache?: BlockCache
	) => {

It's annoying that it needs to take 2 schemas (blocknote & prosemirror) and the blockCache. I think that this could be aleviated though. The prosemirror schema has a cached object which can store the blockCache & blocknote schema inside of it. This would make most methods only ever need a tr and schema

[YousefED]

I prefer the explicitness of what we have here, but I think the tradeoff that it makes are methods that need to take a ton of arguments, which is a code smell imo.

ok! let's go for this approach then 👍

It's annoying that it needs to take 2 schemas (blocknote & prosemirror) and the blockCache. I think that this could be aleviated though. The prosemirror schema has a cached object which can store the blockCache & blocknote schema inside of it. This would make most methods only ever need a tr and schema

We could also just create a type { schema, pmSchema, blockCache }? we could even pass in this from the editor if we'd like (or we create a wrapper object). Not sure if pm cached has any benefits to this (and downside is that it's untyped)

[nperez0111]

We could also just create a type { schema, pmSchema, blockCache }? we could even pass in this from the editor if we'd like (or we create a wrapper object). Not sure if pm cached has any benefits to this (and downside is that it's untyped)

I think I like this better. It turns out that from a transaction's document, you can get a schema. So storing it into the schema makes it really convenient to reach for values you may need. Just as a POC, I cleaned up the insertBlocks method with this. I think the API is a lot cleaner, and nodeToBlock & blockToNode become much simpler too: 2980c6c

[YousefED]

We could also just create a type { schema, pmSchema, blockCache }? we could even pass in this from the editor if we'd like (or we create a wrapper object). Not sure if pm cached has any benefits to this (and downside is that it's untyped)

I think I like this better. It turns out that from a transaction's document, you can get a schema. So storing it into the schema makes it really convenient to reach for values you may need. Just as a POC, I cleaned up the insertBlocks method with this. I think the API is a lot cleaner, and nodeToBlock & blockToNode become much simpler too: 2980c6c

ok! Let's go and see how this works in practice :)

[sentry-io]

Suspect Issues

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

• ‼️ TypeError: Cannot read properties of undefined (reading 'isInGroup') /examples/ui-components/custom-ui View Issue
• ‼️ Error: Node should be a bnBlock, but is instead: quote / View Issue
• ‼️ Error: Block with ID 00f3a57a-f939-430a-b802-a8a9a18362c3 not found / View Issue
• ‼️ Error: Blocks with the following IDs could not be found in the editor: 0bf17f06-7ab5-459c-9a74-51f1b144f51b / View Issue
• ‼️ Error: Block with ID 78540072-d0cf-48a1-a7bd-d50696e798f9 not found / View Issue

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