Migrate to the Document API

editor.commands, editor.state, editor.view, and direct ProseMirror access are deprecated and will be removed in a future version. The Document API (editor.doc) is the replacement for all programmatic document operations.

Why migrate

• Stable contract: the Document API is versioned and engine-agnostic. It will survive the ProseMirror removal.
• 300+ operations: formatting, comments, tables, track changes, lists, images, sections, and more.
• Works everywhere: same operations available in the browser, Node.js SDK, Python SDK, and CLI.

Quick comparison

// Deprecated
editor.commands.toggleBold();
editor.commands.insertTable({ rows: 3, cols: 3 });
editor.commands.addComment({ content: 'Review this' });
const text = editor.state.doc.textContent;

// Document API
editor.doc.format.bold({ target });
editor.doc.create.table({ rows: 3, columns: 3 });
editor.doc.comments.create({ target, content: 'Review this' });
const text = editor.doc.getText();

Common migrations

Reading document content

// Before
const text = editor.state.doc.textContent;
const json = editor.getJSON();

// After
const text = editor.doc.getText();
const content = editor.doc.get();
const markdown = editor.doc.getMarkdown();
const html = editor.doc.getHtml();

Finding and replacing text

// Before
editor.commands.search('ACME Corp');
// manually iterate results...

// After
const result = editor.doc.query.match({
  select: { type: 'text', pattern: 'ACME Corp' },
});
editor.doc.replace({
  target: result.items[0].target,
  text: 'Globex Inc',
});

Formatting

// Before
editor.commands.toggleBold();
editor.commands.toggleItalic();
editor.commands.setColor('#ff0000');
editor.commands.setFontSize(14);
editor.chain().toggleBold().toggleItalic().run();

// After
editor.doc.format.bold({ target });
editor.doc.format.italic({ target });
editor.doc.format.color({ target, value: '#ff0000' });
editor.doc.format.fontSize({ target, value: 14 });
// Apply multiple formats at once:
editor.doc.format.apply({ target, bold: true, italic: true });

Comments

// Before
editor.commands.addComment({ content: 'Please review' });

// After
editor.doc.comments.create({ target, content: 'Please review' });
editor.doc.comments.list();
editor.doc.comments.delete({ id: commentId });

Track changes

// Before
editor.commands.acceptTrackedChange(changeId);
editor.commands.rejectTrackedChange(changeId);

// After
editor.doc.trackChanges.list();
editor.doc.trackChanges.decide({ decision: 'accept', target: { id: changeId } });
editor.doc.trackChanges.decide({ decision: 'reject', target: { id: changeId } });

Tables

// Before
editor.commands.insertTable({ rows: 3, cols: 3 });
editor.commands.addColumnAfter();
editor.commands.deleteRow();

// After
editor.doc.create.table({ rows: 3, columns: 3 });
editor.doc.tables.insertColumn({ tableId, index: 2 });
editor.doc.tables.deleteRow({ tableId, index: 1 });

Lists

// Before
editor.commands.toggleBulletList();
editor.commands.toggleOrderedList();

// After
editor.doc.lists.insert({ target, type: 'bullet' });
editor.doc.lists.insert({ target, type: 'ordered' });
editor.doc.lists.indent({ target });
editor.doc.lists.outdent({ target });

History

// Before
editor.commands.undo();
editor.commands.redo();

// After
editor.doc.history.undo();
editor.doc.history.redo();

Images

// Before
editor.commands.setImage({ src: 'photo.png' });

// After
editor.doc.create.image({ src: 'photo.png' });
editor.doc.images.setSize({ imageId, width: 200, height: 150 });
editor.doc.images.setAltText({ imageId, altText: 'Team photo' });

Accessing the editor from callbacks

The onEditorCreate callback now provides a proxied editor that warns when deprecated properties are accessed. All Document API operations work without warnings:

superdoc.on('editorCreate', ({ editor }) => {
  // No warnings: this is the recommended path
  const content = editor.doc.get();
  editor.doc.format.bold({ target });

  // Console warning: deprecated, will be removed
  const state = editor.state;
  editor.commands.toggleBold();
});

Driving custom React UI

If your migration is also moving the UI side off legacy chains, the destination is superdoc/ui/react. Replace superdoc.on('editor-update', ...) loops and useState(superdoc.activeEditor.commands.X) patterns with the typed hooks: useSuperDocCommand, useSuperDocSelection, useSuperDocComments, useSuperDocTrackChanges, useSuperDocDocument. See Custom UI for the full surface and the reference workspace on GitHub.

Full reference

See Available Operations for the complete mapping of all 300+ operations, and the Document API Reference for detailed input/output schemas.

Need help?

• GitHub Issues
• Discord Community
• Email: [e-mail]