Skip to content

Migration reference

Every rename the codemod performs, the CSS map, and tool-by-tool compatibility.

Run the codemod

Preview first, then apply.

1PreviewPreview what will change
npx -p @bloklabs/core migrate-from-editorjs ./src --dry-run
2ApplyApply the changes to your files
npx -p @bloklabs/core migrate-from-editorjs ./src

Options

--dry-run
Preview changes without modifying files
--verbose
Show detailed output for each file processed
--use-library-i18n
Use Blok's built-in translations (69 locales)

What changes

Every rename the codemod performs, before and after.

Imports

−import EditorJS from '@editorjs/editorjs';
+import { Blok } from '@bloklabs/core';

Tool imports

−import Header from '@editorjs/header';
+import { Header } from '@bloklabs/core/tools';

Types

−import type { EditorConfig } from '@editorjs/editorjs';
+import type { BlokConfig } from '@bloklabs/core';

CSS selectors

−.ce-block
+[data-blok-element]

Default holder

−<div id="editorjs"></div>
+<div id="blok"></div>

Data attributes

−data-id
+data-blok-id

Update your CSS

Blok replaces Editor.js class names with data attributes. Map any custom styles with this reference.

From EditorJSBlok
.codex-editor[data-blok-editor]
.ce-block[data-blok-element]
.ce-block--selected[data-blok-selected="true"]
.ce-toolbar[data-blok-toolbar]
.ce-inline-toolbar[data-blok-testid="inline-toolbar"]
.ce-toolbar__settings-btn[data-blok-settings-toggler]
.ce-popover[data-blok-popover]
data-placeholderdata-blok-placeholder

Migrate custom tools

Block tools port unchanged. Inline tools return a MenuConfig — or wrap the old class and skip the rewrite.

Inline tool render() → MenuConfig

−render() { /* returns an HTMLElement button */ }
+render() { return { icon, name, onActivate, isActive }; }

Fast path — wrapLegacyInlineTool

Wrap an existing EditorJS inline tool class instead of rewriting it. The shim maps the legacy API onto MenuConfig and keeps the tool's title, shortcut, sanitize config and icon. Without it, Blok skips a legacy HTMLElement render() and the tool silently vanishes.

marker: wrapLegacyInlineTool(MarkerTool)

Block tools port unchanged

Blok reads the same keys — render, save, validate, renderSettings, merge, onPaste, and the toolbox/conversionConfig statics. Optionally add setReadOnly(state) for cheaper read-only toggling.

Dropped fields & migration warnings

When migration drops a field with no Blok equivalent, it logs a console.warn naming the block and field — the loss is never silent. Check this table before migrating if you depend on any of them.

BlockDropped field(s)
quotealignment (caption is auto-migrated into a following paragraph)
imagewithBackground
linkToolmeta.site_name
list itemmeta (dropped silently — no console.warn)

Verify your content

Compatibility depends on the tools your content uses, not on your Editor.js version.

Drop-in unchanged

These tools load your saved data as-is.

  • paragraph
  • header
  • code
  • embed
  • marker
  • inlineCode
  • audio

Auto-migrated

Converted at runtime, by the codemod, or both.

  • list
  • checklist
  • toggleList
  • callout
  • image
  • simple-image
  • linkTool
  • delimiter
  • quote
  • table
  • raw
  • warning
  • attaches

Not bundled

Blok ships no equivalent — register your own tool or keep the Editor.js one.

  • personality
  • button

Unknown block types render as stubs and log a "Tool «name» is not found" warning. Their data is preserved — register the tool later and the block comes back.