@openeditor/custom-block

Use this package to add trusted, build-time custom blocks to OpenEditor without adding a ProseMirror node type for each block.

OpenEditor stores every installed block in one atomic customBlock node. A block package owns its data parser, version migration, static output, and asset references. OpenEditor owns the envelope, registry, editor and Viewer lifecycle, missing-block fallback, and safe HTML serialization.

import {
  createOpenEditorCustomBlockRegistry,
  defineOpenEditorCustomBlock,
} from "@openeditor/custom-block";

type CardData = { title: string };

export const card = defineOpenEditorCustomBlock<CardData>({
  id: "acme.card",
  label: "Card",
  version: 1,
  createData: () => ({ title: "Untitled" }),
  parseData: (value) => {
    if (!value || typeof value !== "object" || !("title" in value))
      throw new Error("Card title is required.");
    if (typeof value.title !== "string")
      throw new Error("Card title must be a string.");
    return { title: value.title };
  },
  toHtml: ({ data }) => ({ tag: "article", children: [data.title] }),
  toText: ({ data }) => data.title,
});

export const registry = createOpenEditorCustomBlockRegistry([card]);

The parser is the authoritative data contract. Use the same registry in the browser, backend, publisher, migration, and exporters. This prevents validation rules from drifting across environments.

Import React editor adapters from @openeditor/custom-block/editor. Import published Viewer adapters from @openeditor/custom-block/viewer. The Viewer entry point does not import Tiptap or editor code.

Use migrate only while a stored data version is active. The function must return the complete next envelope and increase the version. A final application release can remove the migration after all stored documents use the current version.

Use assets to return host-managed asset IDs and JSON paths. The host authorizes and resolves these opaque IDs. Block packages do not receive storage clients or credentials.

Use conformOpenEditorCustomBlock in each block package test. It verifies initial data, parsing, and safe static output.