refactor: move all instances of BlockNoteSchema to `CustomBlockNote…

…Schema`
TypeCellOS · YousefED · Oct 13, 2025 · Oct 13, 2025 · Oct 16, 2025 · Oct 16, 2025
commit 750a942d8548d35c39da89e43fc3b214976fabd3
diff --git a/packages/core/src/api/pmUtil.ts b/packages/core/src/api/pmUtil.ts
@@ -1,7 +1,7 @@
 import type { Node, Schema } from "prosemirror-model";
 import { Transform } from "prosemirror-transform";
 import type { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
-import { BlockNoteSchema } from "../blocks/BlockNoteSchema.js";
+import { CustomBlockNoteSchema } from "../schema/schema.js";
 import type { BlockSchema } from "../schema/blocks/types.js";
 import type { InlineContentSchema } from "../schema/inlineContent/types.js";
 import type { StyleSchema } from "../schema/styles/types.js";
@@ -25,12 +25,8 @@ export function getBlockNoteSchema<
   BSchema extends BlockSchema,
   I extends InlineContentSchema,
   S extends StyleSchema,
->(schema: Schema): BlockNoteSchema<BSchema, I, S> {
-  return getBlockNoteEditor(schema).schema as unknown as BlockNoteSchema<
-    BSchema,
-    I,
-    S
-  >;
+>(schema: Schema): CustomBlockNoteSchema<BSchema, I, S> {
+  return getBlockNoteEditor(schema).schema as any;
 }
 
 export function getBlockSchema<BSchema extends BlockSchema>(

diff --git a/packages/core/src/blocks/BlockNoteSchema.ts b/packages/core/src/blocks/BlockNoteSchema.ts
@@ -38,7 +38,7 @@ export class BlockNoteSchema<
      * A list of custom Styles that should be available in the editor.
      */
     styleSpecs?: SSpecs;
-  }): BlockNoteSchema<
+  }): CustomBlockNoteSchema<
     BSpecs extends undefined
       ? BlockSchemaFromSpecs<typeof defaultBlockSpecs>
       : BlockSchemaFromSpecs<NonNullable<BSpecs>>,
@@ -49,7 +49,7 @@ export class BlockNoteSchema<
       ? StyleSchemaFromSpecs<typeof defaultStyleSpecs>
       : StyleSchemaFromSpecs<NonNullable<SSpecs>>
   > {
-    return new BlockNoteSchema<any, any, any>({
+    return new CustomBlockNoteSchema<any, any, any>({
       blockSpecs: options?.blockSpecs ?? defaultBlockSpecs,
       inlineContentSpecs:
         options?.inlineContentSpecs ?? defaultInlineContentSpecs,

diff --git a/packages/core/src/editor/BlockNoteExtensions.ts b/packages/core/src/editor/BlockNoteExtensions.ts
@@ -49,6 +49,7 @@ import {
   BlockNoteDOMAttributes,
   BlockSchema,
   BlockSpecs,
+  CustomBlockNoteSchema,
   InlineContentSchema,
   InlineContentSpecs,
   StyleSchema,
@@ -59,7 +60,6 @@ import type {
   BlockNoteEditorOptions,
   SupportedExtension,
 } from "./BlockNoteEditor.js";
-import { BlockNoteSchema } from "../blocks/BlockNoteSchema.js";
 
 type ExtensionOptions<
   BSchema extends BlockSchema,
@@ -94,7 +94,7 @@ type ExtensionOptions<
   >;
   tabBehavior?: "prefer-navigate-ui" | "prefer-indent";
   comments?: {
-    schema?: BlockNoteSchema<any, any, any>;
+    schema?: CustomBlockNoteSchema;
     threadStore: ThreadStore;
     resolveUsers?: (userIds: string[]) => Promise<User[]>;
   };

diff --git a/packages/core/src/exporter/Exporter.ts b/packages/core/src/exporter/Exporter.ts
@@ -1,8 +1,8 @@
-import { BlockNoteSchema } from "../blocks/BlockNoteSchema.js";
 import { COLORS_DEFAULT } from "../editor/defaultColors.js";
 import {
   BlockFromConfig,
   BlockSchema,
+  CustomBlockNoteSchema,
   InlineContent,
   InlineContentSchema,
   StyleSchema,
@@ -45,7 +45,7 @@ export abstract class Exporter<
   TS,
 > {
   public constructor(
-    _schema: BlockNoteSchema<B, I, S>, // only used for type inference
+    _schema: CustomBlockNoteSchema<B, I, S>, // only used for type inference
     protected readonly mappings: {
       blockMapping: BlockMapping<B, I, S, RB, RI>;
       inlineContentMapping: InlineContentMapping<I, S, RI, TS>;

diff --git a/packages/core/src/exporter/mapping.ts b/packages/core/src/exporter/mapping.ts
@@ -1,7 +1,7 @@
-import { BlockNoteSchema } from "../blocks/BlockNoteSchema.js";
 import {
   BlockFromConfigNoChildren,
   BlockSchema,
+  CustomBlockNoteSchema,
   InlineContentFromConfig,
   InlineContentSchema,
   StyleSchema,
@@ -64,7 +64,7 @@ export function mappingFactory<
   B extends BlockSchema,
   I extends InlineContentSchema,
   S extends StyleSchema,
->(_schema: BlockNoteSchema<B, I, S>) {
+>(_schema: CustomBlockNoteSchema<B, I, S>) {
   return {
     createBlockMapping: <R, RI>(mapping: BlockMapping<B, I, S, R, RI>) =>
       mapping,

diff --git a/packages/core/src/schema/schema.ts b/packages/core/src/schema/schema.ts
@@ -26,10 +26,40 @@ function removeUndefined<T extends Record<string, any> | undefined>(obj: T): T {
   ) as T;
 }
 
+/**
+ * Do note that this is separate from the `BlockNoteSchema` which is now reduced to a simple factory for instantiating a {@link CustomBlockNoteSchema} instance.
+ * In the future, we will rename the `BlockNoteSchema` to `DefaultBlockNoteSchema` and this will be the default schema that is used when no schema is passed to the editor.
+ * At that time, `CustomBlockNoteSchema` will be renamed to `BlockNoteSchema` and this will be the base class for all schemas.
+ */
+
+/**
+ * The CustomBlockNoteSchema class defines the shape of the schema that BlockNote uses, it defines all of the blocks, inline content, and styles that are available in the editor.
+ * You can create a custom schema by extending the CustomBlockNoteSchema class and passing in the blocks, inline content, and styles that you want to use.
+ *
+ * @example
+ * ```typescript
+ * const schema = new CustomBlockNoteSchema({
+ *   blockSpecs: {
+ *     block: { type: "block", content: "styled" },
+ *   },
+ * });
+ * // extending the schema
+ * const extendedSchema = schema.extend({
+ *   blockSpecs: {
+ *     block: { type: "block", content: "styled" },
+ *   },
+ * });
+ *
+ * // using the schema
+ * const editor = new BlockNoteEditor({
+ *   schema: extendedSchema,
+ * });
+ * ```
+ */
 export class CustomBlockNoteSchema<
-  BSchema extends BlockSchema,
-  ISchema extends InlineContentSchema,
-  SSchema extends StyleSchema,
+  BSchema extends BlockSchema = Record<string, never>,
+  ISchema extends InlineContentSchema = Record<string, never>,
+  SSchema extends StyleSchema = Record<string, never>,
 > {
   // Helper so that you can use typeof schema.BlockNoteEditor
   public readonly BlockNoteEditor: BlockNoteEditor<BSchema, ISchema, SSchema> =

diff --git a/packages/react/src/editor/BlockNoteContext.ts b/packages/react/src/editor/BlockNoteContext.ts
@@ -1,6 +1,6 @@
 import {
   BlockNoteEditor,
-  BlockNoteSchema,
+  CustomBlockNoteSchema,
   BlockSchema,
   DefaultBlockSchema,
   DefaultInlineContentSchema,
@@ -33,7 +33,7 @@ export function useBlockNoteContext<
   ISchema extends InlineContentSchema = DefaultInlineContentSchema,
   SSchema extends StyleSchema = DefaultStyleSchema,
 >(
-  _schema?: BlockNoteSchema<BSchema, ISchema, SSchema>,
+  _schema?: CustomBlockNoteSchema<BSchema, ISchema, SSchema>,
 ): BlockNoteContextValue<BSchema, ISchema, SSchema> | undefined {
   const context = useContext(BlockNoteContext) as any;
 

diff --git a/packages/react/src/hooks/useBlockNoteEditor.ts b/packages/react/src/hooks/useBlockNoteEditor.ts
@@ -1,6 +1,6 @@
 import {
   BlockNoteEditor,
-  BlockNoteSchema,
+  CustomBlockNoteSchema,
   BlockSchema,
   DefaultBlockSchema,
   DefaultInlineContentSchema,
@@ -20,7 +20,7 @@ export function useBlockNoteEditor<
   ISchema extends InlineContentSchema = DefaultInlineContentSchema,
   SSchema extends StyleSchema = DefaultStyleSchema,
 >(
-  _schema?: BlockNoteSchema<BSchema, ISchema, SSchema>,
+  _schema?: CustomBlockNoteSchema<BSchema, ISchema, SSchema>,
 ): BlockNoteEditor<BSchema, ISchema, SSchema> {
   const context = useBlockNoteContext(_schema);
 

diff --git a/packages/xl-ai/src/api/schema/schemaToJSONSchema.ts b/packages/xl-ai/src/api/schema/schemaToJSONSchema.ts
@@ -1,5 +1,5 @@
 import {
-  BlockNoteSchema,
+  CustomBlockNoteSchema,
   BlockSchema,
   InlineContentSchema,
   PropSchema,
@@ -262,7 +262,7 @@ function blockSchemaToJSONSchema(schema: BlockSchema) {
 }
 
 function schemaOps(
-  schema: BlockNoteSchema<BlockSchema, InlineContentSchema, StyleSchema>,
+  schema: CustomBlockNoteSchema<BlockSchema, InlineContentSchema, StyleSchema>,
 ) {
   const clone = {
     blockSchema: schema.blockSchema,
@@ -309,12 +309,16 @@ function schemaOps(
 }
 
 export function blockNoteSchemaToJSONSchema(
-  schema: BlockNoteSchema<any, any, any>,
+  schema: CustomBlockNoteSchema<any, any, any>,
 ) {
   schema = schemaOps(schema)
     .removeFileBlocks()
     .removeDefaultProps()
-    .get() as BlockNoteSchema<BlockSchema, InlineContentSchema, StyleSchema>;
+    .get() as CustomBlockNoteSchema<
+    BlockSchema,
+    InlineContentSchema,
+    StyleSchema
+  >;
   return {
     $defs: {
       styles: styleSchemaToJSONSchema(schema.styleSchema),

diff --git a/packages/xl-docx-exporter/src/docx/docxExporter.ts b/packages/xl-docx-exporter/src/docx/docxExporter.ts
@@ -1,6 +1,6 @@
 import {
   Block,
-  BlockNoteSchema,
+  CustomBlockNoteSchema,
   BlockSchema,
   COLORS_DEFAULT,
   InlineContentSchema,
@@ -54,7 +54,7 @@ export class DOCXExporter<
     /**
      * The schema of your editor. The mappings are automatically typed checked against this schema.
      */
-    protected readonly schema: BlockNoteSchema<B, I, S>,
+    protected readonly schema: CustomBlockNoteSchema<B, I, S>,
     /**
      * The mappings that map the BlockNote schema to the docxjs content.
      * Pass {@link docxDefaultSchemaMappings} for the default schema.

diff --git a/packages/xl-email-exporter/src/react-email/reactEmailExporter.tsx b/packages/xl-email-exporter/src/react-email/reactEmailExporter.tsx
@@ -1,6 +1,5 @@
 import {
   Block,
-  BlockNoteSchema,
   BlockSchema,
   COLORS_DEFAULT,
   DefaultProps,
@@ -9,6 +8,7 @@ import {
   InlineContentSchema,
   StyleSchema,
   StyledText,
+  CustomBlockNoteSchema,
 } from "@blocknote/core";
 import {
   Body,
@@ -36,7 +36,7 @@ export class ReactEmailExporter<
   React.ReactElement<HTMLSpanElement>
 > {
   public constructor(
-    public readonly schema: BlockNoteSchema<B, I, S>,
+    public readonly schema: CustomBlockNoteSchema<B, I, S>,
     mappings: Exporter<
       NoInfer<B>,
       NoInfer<I>,

diff --git a/packages/xl-multi-column/src/blocks/schema.ts b/packages/xl-multi-column/src/blocks/schema.ts
@@ -1,4 +1,5 @@
 import {
+  CustomBlockNoteSchema,
   BlockNoteSchema,
   BlockSchema,
   InlineContentSchema,
@@ -21,7 +22,7 @@ export const withMultiColumn = <
   I extends InlineContentSchema,
   S extends StyleSchema,
 >(
-  schema: BlockNoteSchema<B, I, S>,
+  schema: CustomBlockNoteSchema<B, I, S>,
 ) => {
   return schema.extend({
     blockSpecs: {

diff --git a/packages/xl-odt-exporter/src/odt/odtExporter.tsx b/packages/xl-odt-exporter/src/odt/odtExporter.tsx
@@ -1,6 +1,6 @@
 import {
   Block,
-  BlockNoteSchema,
+  CustomBlockNoteSchema,
   BlockSchema,
   COLORS_DEFAULT,
   Exporter,
@@ -49,7 +49,7 @@ export class ODTExporter<
   public readonly options: ExporterOptions;
 
   constructor(
-    protected readonly schema: BlockNoteSchema<B, I, S>,
+    protected readonly schema: CustomBlockNoteSchema<B, I, S>,
     mappings: Exporter<
       NoInfer<B>,
       NoInfer<I>,

diff --git a/packages/xl-pdf-exporter/src/pdf/pdfExporter.tsx b/packages/xl-pdf-exporter/src/pdf/pdfExporter.tsx
@@ -1,8 +1,8 @@
 import {
   Block,
-  BlockNoteSchema,
   BlockSchema,
   COLORS_DEFAULT,
+  CustomBlockNoteSchema,
   DefaultProps,
   Exporter,
   ExporterOptions,
@@ -78,7 +78,7 @@ export class PDFExporter<
     /**
      * The schema of your editor. The mappings are automatically typed checked against this schema.
      */
-    protected readonly schema: BlockNoteSchema<B, I, S>,
+    protected readonly schema: CustomBlockNoteSchema<B, I, S>,
     /**
      * The mappings that map the BlockNote schema to the react-pdf content.
      *