Migrating

@better-rich-text/migrate moves an existing TinyMCE or Froala integration across. It does three jobs:

• Translates an editor configuration object into createRichTextEditor options, with a warning for everything it could not map.

• Cleans HTML saved by those editors (bookmarks, helper attributes, vendor classes) so it loads as plain semantic content.

• Offers a small tinymce-shaped facade, so an application can switch editors before rewriting every call site.

The package reads public option names and stored markup only. It does not import or bundle either editor.

Quick start

import { createRichTextEditor, standardPreset } from '@better-rich-text/core';
import { fromTinyMceConfig } from '@better-rich-text/migrate';

const result = fromTinyMceConfig({
  selector: '#body',
  plugins: 'lists link image table code',
  toolbar: 'undo redo | blocks | bold italic | bullist numlist | link image table | code',
  height: 400,
  menubar: false,
});

for (const warning of result.warnings) console.warn(warning.option, warning.message);
const editor = createRichTextEditor('#body', result.options);

fromFroalaConfig(config) works the same way. Both return:

The translator imports no plugin packages, so it does not grow your bundle. To get ready-to-use plugins and features lists, pass the objects you import:

import { documentsFeature, documentsPlugin } from '@better-rich-text/plugin-documents';
import { createImagePlugin } from '@better-rich-text/plugin-image';

const result = fromTinyMceConfig(config, {
  plugins: { documentsPlugin, createImagePlugin },
  features: { documentsFeature },
  preset: standardPreset,
});
// result.options.preset now uses an image plugin wired to your upload endpoint.

TinyMCE options

Options not listed produce a warning with the message "Option not migrated".

TinyMCE toolbar

newdocument, copy, cut, paste, selectall, openlink and other unlisted buttons go into unsupported; the first five are menu bar items instead. Group separators (|) are kept.

TinyMCE plugins

Froala options

Froala toolbar

| inlineClass, inlineStyle, paragraphStyle | styles | | help | help | | insertFile, insertFiles, imageManager | assets | | insertAnchor | anchor | | pageBreak | pageBreak | | spellChecker | proofing | | trackChanges | suggest | | | |

selectAll, markdown, save and fontAwesome go into unsupported.

Froala plugins

Events

Content

HTML saved by either editor can carry editor-only markup. cleanEditorHtml removes it and leaves the content:

import { cleanEditorHtml } from '@better-rich-text/migrate';

const { html, source, changes } = cleanEditorHtml(storedHtml);
// source: 'tinymce' | 'froala' | 'unknown'; changes: what was removed or converted

It is a string-to-string function with no DOM, so it can run in a batch job over stored records. HTML without vendor markup comes back unchanged.

To clean content as it is loaded and pasted, add the plugin. It hooks the parser: html.parse.input cleans string input, and html.parse.element handles HTML the browser has already parsed (as setHTML and paste do). After a parse that changed something it fires the migrate.cleaned action.

import { migrationPlugin } from '@better-rich-text/migrate';

const editor = createRichTextEditor('#body', { plugins: [migrationPlugin()], content: storedHtml });
editor.editor.hooks.addAction('migrate.cleaned', ({ source, changes }) => console.info(source, changes));

contentPolicyPlugin({ allowedTags, deniedTags, deniedAttributes }) applies element rules before the schema parser. Denied tags are removed with their content; tags outside the allow list are flattened so their text stays.

Uploads

The translators wrap existing upload endpoints so the server does not change:

import { createImagePlugin } from '@better-rich-text/plugin-image';
import { tinyMceHandlerProvider, urlUploadProvider } from '@better-rich-text/migrate';

// TinyMCE images_upload_handler, unchanged.
const fromHandler = createImagePlugin({ provider: tinyMceHandlerProvider(images_upload_handler) });

// A Froala endpoint that answers { link }.
const fromUrl = createImagePlugin({
  provider: urlUploadProvider({ url: '/upload_image', field: 'file', params: { folder: 'posts' }, responseKey: 'link' }),
});

Replace the image plugin in your preset with the new one (the generated code shows how).

Facade

createTinyMceShim gives a tinymce-shaped object for an incremental switch:

import { createRichTextEditor } from '@better-rich-text/core';
import { createTinyMceShim } from '@better-rich-text/migrate';

const tinymce = createTinyMceShim({ create: createRichTextEditor });
const [editor] = await tinymce.init({ selector: '#body', plugins: 'lists link', toolbar: 'bold italic | bullist' });
editor.setContent('<p>Hello</p>');
editor.execCommand('Bold');
editor.on('change', () => save(editor.getContent()));

The facade covers common integration code. TinyMCE plugins, UI registry calls (editor.ui.registry), editor.dom, editor.selection and editor.formatter are not emulated; use facade.instance to reach the Better Rich Text editor.

Limitations

• Custom formats (style_formats, paragraphStyle, inlineClass) are reported for you to pass to createStylesPlugin; they are not applied automatically. Custom toolbar buttons and menu items are not converted. Rewrite them as toolbar items and custom plugins as Better Rich Text plugins.

• Option values given as functions are only used for upload handlers, setup and init_instance_callback (the last two by the facade).

• Allowed-element rules can only narrow what the installed plugins accept; they cannot add new elements.

• In the browser parse path, Froala video embeds are dropped rather than turned into links. Run cleanEditorHtml on stored content first to keep the links.

• Comments, revisions and suggestions stored inside a vendor service are not recovered from HTML. Export them from the service and import them as records.