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 '@editorjs/editorjs'; // specifier still needs a manual change

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 Blok loads legacy data at runtime it logs a one-time console.warn per block and field naming what was dropped, and migrateLegacyBlocks from @bloklabs/core/migrate does the same — passing onLossyField replaces that console warning with your own callback. migrate() always installs one, so it stays silent and hands you the drops in report.lossyFields instead. The codemod is the exception: it hard-wires an empty warn sink and migrates silently, so check this table before running it if you depend on any of these fields.

BlockDropped field(s)
quotealignment (caption is auto-migrated into a following paragraph)
imagewithBackground
linkToolmeta.site_name
list itemmeta.counterType (meta.checked and meta.start are migrated)
attachesfile.name, file.size, file.extension (the file metadata is dropped when the block becomes a bookmark)
markerthe highlight itself (Editor.js writes <mark class="cdx-marker"> with no inline color; Blok's marker sanitizer allows no attributes on such a mark and preflight resets the UA highlight, so the text survives unhighlighted)

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
  • inlineCode
  • audio

Auto-migrated

Converted by the shared legacy grammar — the same rules run at runtime and in the codemod.

  • 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.