fix(schema-migration): more robust migration of background-color & text-color attributes

[nperez0111]

Summary

This makes some changes to the schema migration to make it slightly more robust. It now:

• Merges attributes the the block it is trying to update the attributes of (i.e. not overriding a heading's level if it has one set)
• Migrates whenever the YDoc actually has content (firstChild) & is trying to update the content of the document, reducing likelihood of race conditions with network
• Adds tests to reduce likelihood of regressions

Rationale

The schema migration was introduced to allow for a client-side migration allowing some of the default attributes (backgroundColor & textColor) on the blockContainer, to be moved to it's containing block. This makes that migration more robust & likely to succeed in migrating the content.

Changes

See above

Impact

Testing

You can create an old YDoc by switching to a previous version of BlockNote & adding some background color & text colors to a block. Then in the current version, you can try to load that document & it should attempt to migrate the colors since it has detected that they were on the incorrect element (present on the blockContainer).

Screenshots/Video

Checklist

• Code follows the project's coding standards.
• Unit tests covering the new feature have been added.
• All existing tests pass.
• The documentation has been updated to reflect the new feature

Additional Notes

[vercel]

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

Project	Deployment	Preview	Updated (UTC)
blocknote	Ready	Preview	Nov 5, 2025 1:13pm
blocknote-website	Ready	Preview	Nov 5, 2025 1:13pm

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

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

@blocknote/code-block

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

@blocknote/core

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

@blocknote/mantine

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

@blocknote/react

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

@blocknote/server-util

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

@blocknote/shadcn

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

@blocknote/xl-ai

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-ai@2154

@blocknote/xl-docx-exporter

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

@blocknote/xl-email-exporter

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

@blocknote/xl-multi-column

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

@blocknote/xl-odt-exporter

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

@blocknote/xl-pdf-exporter

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

commit: 9ad7185