refactor: zod for props #2096

YousefED · 2025-10-13T04:56:03Z

Summary

This PR drops our custom schema for Block and Inline Content Props and uses Zod instead.

Rationale

Less "non-standard" code to maintain
Easier to explain in docs / to LLMs

Changes

Impact

Consumers using custom blocks would need to migrate

TODO: Determine if we want to accept old style props for backwards compatibility

Testing

Mostly by existing unit tests. TODO:

build of examples doesn't pass. couldn't figure out the build errors for withMultiColumn and withPageBreak examples. Playing around with BlockNoteSchema vs CustomBlockNoteSchema. Perhaps @nperez0111 can help here?
Manual testing + code review. @matthewlipski can you help with this (after build + tests pass), and specifically the file blocks and anywhere where block type guards are used
add tests / example for more complex schemas (e.g.: a prop with a nested object). @matthewlipski can you help?
check compatibility with yjs, does it break with Conversion doesn't check types yjs/y-prosemirror#116? (cc @nperez0111)

Screenshots/Video

N/A

Checklist

Code follows the project's coding standards.
Unit tests covering the new feature have been added.
All existing tests pass.
Y: The documentation has been updated to reflect the new feature
Y: Review and add comments + followup work

Additional Notes

Future work:

Migrate style props as well?
Refactor File Blocks / File Props?
Remove / refactor "Partial" blocks as much as possible

vercel · 2025-10-13T04:56:11Z

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

Project	Deployment	Preview	Updated (UTC)
blocknote	Error		Oct 13, 2025 5:03am
blocknote-website	Error		Oct 13, 2025 5:03am

nperez0111 · 2025-10-13T07:52:47Z

packages/core/src/schema/blocks/internal.ts

+        // TBD: this might not be fault proof, but it's also ugly to store prop="&quot;...&quot;" for strings
+        try {
+          const jsonValue = JSON.parse(value);
+          // it was a number / boolean / json object stored as attribute
+          return z.parse(spec, jsonValue);
+        } catch (e) {
+          // it might have been a string directly stored as attribute


I'd recommend https://github.com/unjs/destr & maybe this is helpful? https://zod.dev/codecs?id=jsonschema

nperez0111 · 2025-10-13T08:00:51Z

packages/core/src/schema/blocks/internal.ts

+    const def =
+      spec instanceof z.$ZodDefault ? spec._zod.def.defaultValue : undefined;


I've seen this in a number of places, would prefer to make a util function for this, since it isn't obvious & dependent on zod's API not our own. I don't love reach into zod for this, but don't see another way to do this unless we provide defaults separately

YousefED · 2025-10-13T05:01:26Z

tests/src/unit/core/clipboard/paste/__snapshots__/text/html/pasteImage.json

      "backgroundColor": "default",
      "caption": "",
      "name": "",
+      "previewWidth": undefined,


Note, when getting a block you now also get optional props as undefined. I think this is ok?

cc @nperez0111

Seems fine to me, probably better even.

YousefED · 2025-10-13T05:05:15Z

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

    }
+
+    try {
+      // TODO: props.level type should propagate correctly


@nperez0111 I didn't get this to work with the way blocks are defined. Can you have a look at this or can we pair up?

YousefED · 2025-10-13T05:07:07Z

packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts

  const BC_NODE = editor.pmSchema.nodes["blockContainer"];

  // set default props in case we were passed a partial block
+  // TODO: should be a nicer way for this / or move to caller


fyi, I don't think these functions should take PartialBlocks. I want to review the PartialBlock concept later. My thought at this moment is that they should only be on the highest level, to make calling things like updateBlock / insertBlocks more convenient

YousefED · 2025-10-13T05:12:49Z

packages/core/src/blocks/defaultBlockTypeGuards.ts

 import { Block } from "./defaultBlocks.js";
-import { Selection } from "prosemirror-state";

+// TODO: matthew review + tests


@matthewlipski , you recently refactored this file I think. afaik there are no unit tests covering the type guards. Could you add these? I'm not sure if my implementation matches the scenarios you had in mind

You can also add them to the main branch implementation and then I can migrate them to validate they still work after this zod refactor

Added tests in #2103

YousefED · 2025-10-13T05:15:14Z

packages/core/src/editor/BlockNoteEditor.ts

   */
  comments?: {
-    schema?: BlockNoteSchema<any, any, any>;
+    schema?: CustomBlockNoteSchema<any, any, any>;


@nperez0111 please double check my changes in this file (not sure I correctly get the difference between CustomBlockNoteSchema and BlockNoteSchema)

YousefED · 2025-10-13T05:22:22Z

packages/server-util/src/context/ServerBlockNoteEditor.ts

+  >(
+    options?: Options,
+  ): Options extends {
+    schema: CustomBlockNoteSchema<infer BSchema, infer ISchema, infer SSchema>;


@nperez0111 another schema change

matthewlipski · 2025-10-14T16:57:33Z

add tests / example for more complex schemas (e.g.: a prop with a nested object). @matthewlipski can you help?

@YousefED so with this PR are we introducing the ability to have objects as props alongside strings/numbers/booleans? Because I remember this was something we considered when first making the custom blocks API, but skipped it mainly because objects need to be set on HTML attributes with JSON.stringify so they can then be parsed properly. IIRC we were concerned about the stringified objects making the DOM super messy, and also issues if you have functions since they can't be stringified. Do we have a solution for this?

zod refactor

acc7114

add zod to examples

6847a09

vercel bot had a problem deploying to Preview – blocknote October 13, 2025 04:59 Failure

vercel bot had a problem deploying to Preview – blocknote-website October 13, 2025 05:03 Failure

YousefED changed the title ~~zod refactor~~ refactor: zod for props Oct 13, 2025

nperez0111 reviewed Oct 13, 2025

View reviewed changes

YousefED commented Oct 13, 2025

View reviewed changes

matthewlipski mentioned this pull request Oct 14, 2025

feat: Unit tests for block type guards #2103

Open

4 tasks

		const def =
		spec instanceof z.$ZodDefault ? spec._zod.def.defaultValue : undefined;

Uh oh!

refactor: zod for props #2096

Are you sure you want to change the base?

refactor: zod for props #2096

Conversation

YousefED commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Rationale

Changes

Impact

Testing

Screenshots/Video

Checklist

Additional Notes

Uh oh!

vercel bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nperez0111 Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewlipski commented Oct 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

YousefED commented Oct 13, 2025 •

edited

Loading

vercel bot commented Oct 13, 2025 •

edited

Loading

nperez0111 Oct 13, 2025 •

edited

Loading