Rich Text Extensions

Rich text extensions add Tiptap nodes, marks, and toolbar buttons to the WYSIWYG interface. A field uses an extension only when you select it in the interface's Extensions option.

Tiptap Version Policy

A rich text extension uses the copy of Tiptap that ships with the Data Studio. The extensions SDK does not bundle the shared Tiptap packages, so the editor and your extension use the same ProseMirror classes. ProseMirror checks objects by class, so objects from a second copy of ProseMirror fail these checks and the editor behaves incorrectly.

This makes the Tiptap version part of the extension API. A new Tiptap major version can break every installed rich text extension. Directus shares vue, vue-router, vue-i18n, and pinia with app extensions in the same way.

Shared Tiptap Packages

Import the following packages directly in your extension. The extensions SDK marks them as external when it builds, so your bundle uses the Data Studio's copy and does not include them.

• @tiptap/core
• @tiptap/vue-3
• These @tiptap/pm subpaths: commands, dropcursor, gapcursor, history, keymap, model, schema-list, state, tables, transform, and view. For example, @tiptap/pm/keymap.

Each @tiptap/pm subpath re-exports one ProseMirror package. For example, @tiptap/pm/keymap re-exports prosemirror-keymap. When your code or a package you install imports a ProseMirror package behind a shared subpath by its own name, the extensions SDK changes the import to that subpath. So you can install Tiptap packages that use ProseMirror, such as @tiptap/extension-table. The SDK bundles the code of the package itself, but it uses the Data Studio's copy of ProseMirror.

The Data Studio does not use @tiptap/pm/changeset or @tiptap/pm/inputrules, so the extensions SDK bundles them into your extension. This is safe. They do not contain ProseMirror classes or plugin keys that the editor checks, and their own ProseMirror imports go to the shared subpaths.

If you install other Tiptap packages, use a version from the same Tiptap major as Directus.

Version Guarantees

• Directus pins the Tiptap major version. Tiptap minor and patch updates can ship in any Directus release.
• A new Tiptap major version ships only in a new Directus major version.
• The breaking changes page for that Directus version lists the Tiptap upgrade.

Set the Host Range

The host field in your extension's package.json declares the Directus versions it supports. Set it to a caret range on the Directus version you build against.

"directus:extension": {
    "type": "richtext",
    "path": "dist/index.js",
    "source": "src/index.js",
    "host": "^12.4.0"
}

A caret range stops at the next major version. When a Directus major version upgrades Tiptap, your range no longer matches it.

The Marketplace compares host with the project's Directus version. When the range does not match, the extension's page shows Compatibility not guaranteed.

Upgrade After a Tiptap Major Version

When a Directus major version upgrades Tiptap, update your extension before your users upgrade.

1. Read the breaking changes for the new Directus version and Tiptap's upgrade notes.
2. Update the Tiptap APIs your extension uses.
3. Build the extension and test it on the new Directus version.
4. Set host to the new major version, for example ^13.0.0.
5. Publish the update as a new major version of your extension.

Next Steps

Read about publishing to the Marketplace, the WYSIWYG interface options, and custom formats for the editor.