tinymce-docs/modules/ROOT/pages/migration-from-7x.adoc

= Migrating from {productname} 7 to {productname} {productmajorversion}
:navtitle: Migrating from TinyMCE 7
:description: Guidance for migrating from TinyMCE 7 to TinyMCE 8
:keywords: migration, considerations, premigration, pre-migration
:release-version: 8.0
:page-toclevels: 3

== Introduction

This guide provides a comprehensive overview of the breaking changes introduced in {productname} {release-version}, along with the necessary steps to migrate from {productname} 7.x. It covers key updates to APIs, plugins, and service configurations, including deprecated methods, renamed components, and removed features. These changes are designed to enhance performance, simplify configuration, and align with modern web standards, ensuring a smoother transition and continued compatibility for your integrations.

[IMPORTANT]
.Breaking Changes Quick Reference
====
The following table summarizes all breaking changes in {productname} {release-version}. Each item links to detailed information further in the guide.

Any items marked **"High"** level require immediate attention during migration.

[cols="2,3,1",options="header"]
|===
|Breaking Change |Impact |Level
|xref:license-key-system-update[License Key System Update]
|Self-hosted deployments now require a new license key format and license key manager. Old keys are **not compatible**.
|High

|xref:dompurify-update-breaking-change[DOMPurify Update and Stricter Sanitization]
|Sanitization is now stricter; content previously allowed may be stripped or altered. See migration guide for details.
|High

|xref:editor-selection-setcontent-deprecated[editor.selection.setContent] Deprecated
|Method deprecated. Use `editor.insertContent` instead.
|Medium

|xref:fire-method-deprecation[fire()] Method Deprecation
|Method deprecated. Use `dispatch()` for event handling.
|Medium

|xref:pagebreak-split-block-default[pagebreak_split_block Default Value]
|The default value changed from `false` to `true`, affecting how page breaks interact with block elements.
|Low

|xref:editor-documentbaseurl-removal[editor.documentBaseUrl] Removal
|Undocumented property removed. Use `editor.editorManager.documentBaseURI` instead.
|Low

|xref:skipfocus-consolidation[skipFocus and skip_focus] Consolidation
|Options consolidated to `skipFocus` in `ToggleToolbarDrawer`.
|Low
|===
====

[[license-key-system-update]]
=== Transition from Version 7 License Keys to Version {release-version} License Keys
// #EPIC-192

[IMPORTANT]
====
This section applies to self-hosted installations only. For cloud deployments, license key management is handled automatically.
====

{productname} {release-version} introduces an enhanced license key system that requires specific attention during migration. The complete licensing documentation xref:license-key.adoc[License Key Management] covers:

* Detailed explanations of all license types (GPL, Commercial, GPL with Premium Features)
* Time-based vs Version-locked license key differences
* License states (Active, Grace Period, Expired, Invalid)
* Deployment options (Cloud-only, Self-hosted, Hybrid)
* Step-by-step configuration examples for each setup
* Commercial License Key Manager setup and requirements
* Troubleshooting and FAQ

==== Key Migration Considerations

* *License Key Format Change:* Version 7 keys are **not compatible** with {productname} {release-version}. New keys use the prefix `T8LK:` for commercial licenses or `GPL+T8LK:` for GPL with Premium Features.
* *Mandatory Key Requirement:* Self-hosted deployments now **require** a valid license key; without one, the editor will be set to readonly.
* *Commercial License Manager:* Self-hosted commercial deployments **require** the new license key manager addon.

==== Migration Steps

. *Obtain New License Key:*
** link:https://www.tiny.cloud/contact/[Contact us] to obtain a new {productname} {release-version} license key, or use `gpl` for the open source version. See: xref:license-key.adoc#setting-the-license[setting the license] for details.

. *Update Configuration:*
+
[source, javascript]
----
// Old TinyMCE 7 configuration
tinymce.init({
  selector: '#editor',
  // No license key required
});

// New TinyMCE 8 configuration
tinymce.init({
  selector: '#editor',
  license_key: 'T8LK:...'  // New format required
});
----

==== License Key Manager Setup

When migrating to TinyMCE {release-version} with a commercial license, the license key manager addon is required for the editor to operate. The setup varies based on your deployment method:

. *CDN/Static Hosting:*
** Ensure the supplied `licensekeymanager` folder is in your {productname} plugins directory:
+
[tree]
----
your-site/
├── tinymce/
│ └── plugins/
│   ├── licensekeymanager/     # Add this folder
│   │   ├── plugin.min.js
│   │   └── index.js
│   └── ... other plugins
----

. *NPM/Module Bundler:*
** Install TinyMCE and ensure the license key manager is imported:
+
[source, javascript]
----
// Import TinyMCE
import tinymce from 'tinymce';

// Import the license key manager
import 'tinymce/plugins/licensekeymanager';

tinymce.init({
  selector: '#editor',
  license_key: 'T8LK:...'  // New format required
});
----

. *React/Next.js:*
** When using the `@tinymce/tinymce-react` package:
+
[source, javascript]
----
import { Editor } from '@tinymce/tinymce-react';
import 'tinymce/plugins/licensekeymanager';

export default function MyEditor() {
  return (
    <Editor
      init={{
        license_key: 'T8LK:...'
      }}
    />
  );
}
----

. *PHP/Laravel:*
** Ensure the license key manager is included when publishing {productname} assets:
+
[source, php]
----
<script src="{{ asset('path/to/tinymce/tinymce.min.js') }}"></script>
<script src="{{ asset('path/to/tinymce/plugins/licensekeymanager/plugin.min.js') }}"></script>
<script>
tinymce.init({
  selector: '#editor',
  license_key: 'T8LK:...'
});
</script>
----

[IMPORTANT]
====
* The license key manager is automatically included when using Tiny Cloud.
* The plugin does not need to be added to the `plugins` configuration option.
* For bundled applications, the license key manager must be loaded before {productname} initialization.
* For bundled applications, ensure the license key manager is not excluded during build optimization.
====

For complete details on license key manager setup and troubleshooting, see xref:license-key.adoc##setting-up-the-commercial-license-key-manager[Setting up the Commercial License Key Manager].

**License Migration checklist:**

* [ ] Contact support for new {productname} {release-version} license key or use GPL for the open source version
* [ ] Install license key manager addon for commercial licenses
* [ ] Update configuration with new license key format
* [ ] Test editor functionality with new license
* [ ] Verify all premium features are working

[[dompurify-update-breaking-change]]
=== DOMPurify Update and Stricter Sanitization (Breaking Change)
// #TINY-12056

{productname} {release-version} updates the DOMPurify dependency to version 3.2.6 and enables the `SAFE_FOR_XML` flag by default. This is a breaking change: content that previously passed sanitization in {productname} 7 may now be stripped or altered during the sanitization process.

[IMPORTANT]
====
This change improves security and aligns with DOMPurify's recommended defaults. However, existing content and integrations that relied on the previous, less strict sanitization behavior may be impacted.
====

==== Key Changes

* **DOMPurify upgraded to 3.2.6** — The custom patch is now included upstream; maintaining a forked patch is no longer required.
* **`SAFE_FOR_XML` enabled** — This setting enforces stricter handling of comments and attribute values, preventing certain XSS vectors.
* **Content Impact** — HTML comments containing tags, Internet Explorer conditional comments, and attributes with HTML-like values may now be removed during sanitization. Content that was previously allowed may be stripped.

==== Migration Guidance

* Review workflows and test content that previously relied on relaxed sanitization.
* If custom comment handling is required, consider using DOMPurify hooks as recommended by the maintainers.

.Example: Content Differences
|===
|Content |{productname} 7 Output |{productname} {release-version} Output

|`<div><!-- <p>Hello World</p> --></div>`
|`<div><!-- <p>Hello World</p> --></div>`
|`<div></div>`

|`<iframe><!-- Hello World --></iframe>`
|`<p><iframe sandbox=""><!-- Hello World --></iframe></p>`
|``

|`<script><!-- Hello World --></script>`
|`<script><!-- Hello World --></script>`
|``
|===

[NOTE]
====
For information on disabling DOMPurify sanitization (not recommended), see xref:security.adoc#xss_sanitization-option[xss_sanitization option].
====

== Core API Changes

[discrete]
=== Breaking Changes Overview

IMPORTANT: The following sections detail important changes that require updates to your code. Please review each section carefully.

=== Removed Methods

[[editor-selection-setcontent-deprecated]]
==== editor.selection.setContent
[.discrete]
// #TINY-12109

The `editor.selection.setContent` API has been deprecated and will be removed in {productname} 9.

.Example Usage
[source,javascript]
----
// Deprecated in TinyMCE 8, will be removed in 9
editor.selection.setContent('<p>New content</p>');

// Recommended replacement
editor.insertContent('<p>New content</p>');
----

*Impact*: This change simplifies content manipulation by consolidating insertion methods.

**Migration checklist:**

* [ ] Replace all instances of `editor.selection.setContent` with `editor.insertContent`
* [ ] Update custom plugins that use the old method
* [ ] Test content insertion in your editor instances

'''

[[editor-documentbaseurl-removal]]
==== editor.documentBaseUrl
[.discrete]
// #TINY-12182

The undocumented `editor.documentBaseUrl` property has been removed.

.Example Usage
[source,javascript]
----
// Removed in TinyMCE 8
console.log('documentBaseUrl', editor.documentBaseUrl);

// Use this instead
console.log('documentBaseURI', editor.documentBaseURI.getURI());
----

TIP: Use `tinymce.activeEditor.documentBaseURI.getURI()` for all base URL operations.

.Required Changes

To update all references of `documentBaseUrl` to the new API, replace any usage of `editor.documentBaseUrl` (or similar) with `tinymce.activeEditor.documentBaseURI.getURI()`. The property `documentBaseUrl` has been removed, and the correct way to access the document base URL is now through the `documentBaseURI` property, which is a URI object. You can then call `.getURI()` on it to get the string value of the URL.

.For example, update this:
[source, js]
----
const baseUrl = editor.documentBaseUrl;
----

to:

[source, js]
----
const baseUrl = tinymce.activeEditor.documentBaseURI.getURI();
----

This change is necessary because the undocumented `editor.documentBaseUrl` API has been removed to improve URL handling consistency. The new approach uses the documented `documentBaseURI` property, which provides a URI object with methods such as `getURI()` to retrieve the full URL string. 

For more information see: link:https://www.tiny.cloud/docs/tinymce/latest/apis/tinymce.editor/#properties[tinymce.editor/#properties].

**Migration checklist:**

* [ ] Search your codebase for all instances of `editor.documentBaseUrl`.
* [ ] Replace them with `tinymce.activeEditor.documentBaseURI.getURI()` (or `editor.documentBaseURI.getURI()` if you have an `editor` reference).

'''

[[skipfocus-consolidation]]
==== skipFocus and skip_focus
// #TINY-12044

The `skipFocus` and `skip_focus` options for the `ToggleToolbarDrawer` command have been consolidated into a single, more consistent argument. This reduces API complexity and clarifies the intended behavior.

[source, javascript]
----
// Old approach (Deprecated) in TinyMCE 8
editor.execCommand('ToggleToolbarDrawer', { skip_focus: false }, { skipFocus: true });

// New approach (Recommended)
editor.execCommand('ToggleToolbarDrawer', false, { skipFocus: true });
----

**Impact**: This change simplifies focus management, reducing the risk of confusion and unexpected behavior.

**Migration checklist:**

* [ ] Locate all instances of `ToggleToolbarDrawer` command usage
* [ ] Replace `skip_focus` with `skipFocus` in command options
* [ ] Update any custom plugins using this command
* [ ] Test toolbar drawer behavior after changes


=== Deprecated Methods

[[fire-method-deprecation]]
==== `fire()`
// #TINY-12012, ref TINY-8102

The `fire()` method has been replaced by `dispatch()` for event handling. The `fire()` method will be removed in {productname} 9 to avoid confusion with its name.

[source, javascript]
----
// Deprecated in TinyMCE 8, will be removed in 9
// Old approach for dispatching custom events
editor.fire('someEvent');

// New approach for dispatching custom events
editor.dispatch('someEvent');
----

**Impact**: This change aligns {productname} with modern event handling conventions, making the API more intuitive for developers.

**Migration checklist:**

* [ ] Search codebase for all uses of the `fire()` method
* [ ] Replace each instance with `dispatch()`
* [ ] Review and update third-party plugins
* [ ] Test all custom event handling


=== Plugin Updates

==== Language Pack Filename Changes
// #TINY-12090

Language pack filenames have been standardized to follow the RFC5646 format. This update ensures consistent language handling across platforms and improves internationalization support. While both the legacy underscore format (e.g., `en_GB.js`) and the new hyphenated format (e.g., `en-GB.js`) are supported in {productname} {release-version}, the underscore format is deprecated and will be removed in {productname} 9. Migrating to the RFC5646 format now will ensure future compatibility and reduce maintenance overhead during upcoming upgrades.

**Impact**: Custom language packs and configurations using the underscore-based format should update before upgrading to {productname} 9 to avoid loading failures.

**Migration checklist:**

* [ ] Identify all language pack files in your deployment
* [ ] Rename files to RFC5646 format (e.g., `en_GB.js` → `en-GB.js`)
* [ ] Update configuration references to language files
* [ ] Update build scripts that handle language files
* [ ] Test language switching in your application
* [ ] Update custom translation files to use the new format

[source, javascript]
----
// Deprecated format (supported only in versions 8.x)
language_url: '/langs/en_GB.js'

// Recommended format
language_url: '/langs/en-GB.js'
----

[IMPORTANT]
Support for the underscore format will be removed in {productname} 9. Early migration is recommended.

==== Update to Image and Accessibility Checker Plugins
// #TINY-12226

The Image and Accessibility Checker plugins now follow the latest W3C standards for decorative images, requiring an empty alt attribute rather than a `+role="presentation"+` attribute. This change helps improve accessibility support.

**Impact**: Customers using these plugins will need to update their configurations to ensure continued compliance with accessibility standards.

**Migration checklist:**

* [ ] Identify images previously using `role="presentation"` for decorative purposes in your content
* [ ] Replace those with empty alt attributes (`alt=""`)
* [ ] Update image plugin configuration if customized
* [ ] Test accessibility checker with updated content

For more information on the changes, see: xref:a11ychecker.adoc##image-rules[Accessibility Checker: Image rules].

[[pagebreak-split-block-default]]
==== Page Break Plugin: Export PDF/Word Compatibility and Option Updates
// #TINY-12013, #TINY-12462

The Page Break plugin has been updated to work out-of-the-box with the xref:exportpdf.adoc[Export to PDF] and xref:exportword.adoc[Export to Word] plugins, addressing a common pain point for developers. As part of this update:

* The default value of the xref:pagebreak.adoc#pagebreak_separator[`pagebreak_separator`] option now uses a block tag (`<div style="break-after: page
* The default value of the xref:pagebreak.adoc#pagebreak_split_block[`pagebreak_split_block`] option has changed from `false` to `true`.

This means that by default, inserting a page break will now automatically split block elements (such as paragraphs, lists, or tables) at the cursor position, and the separator will be compatible with both export services.

**Impact**: These changes improve the export experience and provide a more intuitive editing experience.

**Migration steps:**

* If you want to restore the previous (v7) behavior, where page breaks do not automatically split block elements and use a comment tag as the separator, set both options explicitly in your configuration:

[source, javascript]
----
tinymce.init({
  // ...other configuration options...
  pagebreak_separator: '<!-- my page break -->',
  pagebreak_split_block: false
});
----

=== Technical Improvements and Cleanup

==== Cross-Origin Resource Loading Configuration
// #TINY-12228, TINY-12326

When upgrading to {productname} 8, you will need to review and possibly update how your integration handles cross-origin resource loading. {productname} 8 provides a new configuration option for controlling the `crossorigin` attribute on loaded resources.

**What to check:**

. If you're using {cloudname}:
+
* Ensure your script tag includes both required attributes:
+
[source,html,subs="attributes+"]
----
<script src="{cdnurl}" referrerpolicy="origin" crossorigin="anonymous"></script>
----
+
. If your application loads resources (scripts or stylesheets) from different domains:
+
* Configure the new crossorigin function in your `tinymce.init`:
+
[source, javascript]
----
tinymce.init({
  selector: "textarea",
	crossorigin: (url, resourceType) => {
  // Returning 'anonymous' or 'use-credentials' here would explicitly set the attribute
	// return 'anonymous';
	// return 'use-credentials';
	return undefined; // Omit the 'crossorigin' attribute for all resources by returning undefined
  },
});
----
+
. If you're using content_css from a different domain:

* The `content_css_cors` option takes precedence for stylesheets.
* Review your `content_css` configuration if you use cross-origin stylesheets.

**Migration checklist:**

* [ ] Verify script tag attributes for Cloud deployments.
* [ ] Configure `crossorigin` function if using cross-origin resources.
* [ ] Test resource loading in your deployment environment.
* [ ] Review `content_css` configuration if using cross-origin stylesheets.

For complete details on the new crossorigin function API, see: xref:tinymce-and-cors.adoc#crossorigin[crossorigin configuration option].

==== Removed Empty Files
// #TINY-11287, #TINY-12084

Several empty files have been removed from the codebase to reduce clutter and improve maintenance:

* Empty CSS file from the Comments plugin
* Empty LESS file from the Mentions plugin

**Impact**: These changes have no functional impact but may affect custom build processes that explicitly reference these files.

**Migration checklist:**

* [ ] Check build processes for references to Comments plugin CSS
* [ ] Check build processes for references to Mentions plugin LESS
* [ ] Remove any imports of these empty files
* [ ] Test Comments and Mentions plugins after removal

=== Service and Configuration Changes

==== Discontinuation of Medical English (UK)
// #EPIC-255

[WARNING]
The "Medical English (UK)" dictionary has been removed due to licensing constraints. Customers using this feature must update their configurations accordingly.

**Impact**: Users relying on this dictionary will need to make alternative arrangements for medical-specific spell checking.

**Migration checklist:**

* [ ] Remove "Medical English (UK)" from spellchecker configurations
* [ ] Remove any custom dictionary integrations related to Medical English
* [ ] Test spellchecker functionality with remaining dictionaries
* [ ] Configure alternative medical dictionary if required

==== Decoupling of Service Versions from {productname} Editor
// #EPIC-247, #EPIC-265

Services previously bundled with the editor, such as Java Servlet services, are no longer included in {productname} {release-version} packages. Customers should migrate to xref:bundle-intro-setup.adoc[Containerized service deployments] or consider alternative hosting options.

**Impact**: This reduces the dependency between the editor and backend services, simplifying updates and maintenance.

**Migration steps:**

* Update the applications deployment architecture to use xref:bundle-intro-setup.adoc[Containerized services] where applicable

==== Transition from Java WAR Files to Containerized Services
// #EPIC-247

{productname} {release-version} no longer includes Java WAR files for backend services like the spell checker. Customers are required to migrate to modern Docker/OCI containers for self-hosted deployments.

**Impact**: This reduces infrastructure complexity and aligns with modern DevOps practices.

**Migration checklist:**

* [ ] Inventory current WAR file deployments
* [ ] Review containerization requirements for your environment
* [ ] Plan transition timeline to containerized services
* [ ] Set up container infrastructure (Docker/Kubernetes)
* [ ] Deploy and test containerized services
* [ ] Update service connection configurations
* [ ] Contact link:{supporturl}/[{supportname}] if legacy WAR files are still needed

For more information on deploying the server-side components using Docker, see: xref:bundle-intro-setup.adoc[Containerized service deployments].

== Conclusion

Upgrading to {productname} {release-version} requires integrators to update their API calls, plugin configurations, and service integrations to accommodate the breaking changes introduced in this release. While some adjustments may involve significant code updates, these enhancements are intended to simplify development, and improve the overall editor experience.

For more guidance, refer to the:

* link:https://www.tiny.cloud/docs[{productname} Documentation],
* Utilize our in-house **Ask AI** widget for general support found in the bottom corner of every documentation page, or
* link:https://www.tiny.cloud/contact/[Contact {supportname}] for assistance.

For additional details on {productname} {release-version} changes, see xref:8.0-release-notes.adoc#overview[{productname} {release-version} release notes].