Migrating custom plugins

If you have created and published custom plugins for CKEditor 5, you will need to adjust them to make them work with the new installation methods.

You do not need to follow this guide if your custom plugins are used directly in your project and are not separate packages. In such cases, you can update the plugins along with the projects that use them.

Before you start, follow the usual upgrade path to update your plugin to use the latest version of CKEditor 5. This will rule out any problems that may be caused by upgrading from an outdated version of CKEditor 5.

To ensure that all the dependencies are up-to-date and that the build process is correct, we recommend the following steps:

1. Create a new project using the package generator following the package generator guide.
2. Copy the src, tests, and sample folders of your plugin into the new project.
3. Re-add all the external dependencies, devDependencies, and peerDependencies specific to your plugin to the package.json file.

When you run the CLI, it generates the modern build setup and the imports used across the new ecosystem.

The main changes we have introduced in the new package generator are:

• Making the generated package a valid ECMAScript module,
• Updating the build process to generate bundles for the new installation methods,
• Adding new eslint rules to avoid common errors,
• Updating dependencies.

Next, as required by the JavaScript modules (ESM), you must add the missing file extensions to all files in the src, tests, and sample folders during import.

- import { Plugin } from 'ckeditor5/src/core';
+ import { Plugin } from 'ckeditor5';

-import SomePlugin from './src/someplugin';
+import SomePlugin from './src/someplugin.js';

Imports from the package roots should be changed to ckeditor5.

- import { Plugin } from '@ckeditor/ckeditor5-core';
+ import { Plugin } from 'ckeditor5';

If you run the following command, the ckeditor5-rules/require-file-extensions-in-imports eslint rule should fix most, if not all, problems related to missing file extensions.

npm run lint -- --fix

For some time now, we have strongly discouraged importing from the src folder of the @ckeditor/ckeditor5-* packages. Instead, you should import from the package roots because they provide better TypeScript support and because the src folders are now removed. Always import from the ckeditor5.

// ❌
import Plugin from '@ckeditor/ckeditor5-core/src/plugin.js';

// ❌
import { Plugin } from '@ckeditor/ckeditor5-core';

// ✅
import { Plugin } from 'ckeditor5';

Note that the names of the exports may differ between the src folder and the package root. In the above example, the named Plugin import from @ckeditor/ckeditor5-core/src/plugin.js will be exported under the same name from ckeditor5, but this is not guaranteed. In cases where the names do not match, you will need to modify the import accordingly.

There may also be cases where something you imported from the src folder is not exported from the package root. In such cases, please create a new issue in the CKEditor 5 repository so we can consider adding the missing exports.

If you run the following command, the ckeditor5-rules/allow-imports-only-from-main-package-entry-point eslint rule will list all the places where you need to update the imports.

npm run lint

The same rule applies to the theme folder in the @ckeditor/ckeditor5-* packages. If you need to use icons from this folder, you can likely import them from the package root.

// ❌
import undo from '@ckeditor/ckeditor5-icons/theme/undo.svg';

console.log( undo );

// ✅
import { IconUndo } from 'ckeditor5';

console.log( IconUndo );

If you run the following command, the ckeditor5-rules/allow-imports-only-from-main-package-entry-point eslint rule will list all the places where you need to update the imports.

npm run lint

Update all imports from ckeditor5/src/* and @ckeditor/ckeditor5-* to ckeditor5.

- import { Plugin } from 'ckeditor5/src/core.js';
- import { ButtonView } from 'ckeditor5/src/ui.js';
+ import { Plugin, ButtonView } from 'ckeditor5';

If you run the following command, the ckeditor5-rules/no-legacy-imports eslint rule will list all the places where you need to update the imports.

npm run lint

Run the npm run lint command to see if there are any remaining problems that need to be fixed.

Once you have updated all the imports, it is time to build and validate the bundle for the new installation methods.

1. Build the plugin with the following command. It will create the dist folder with the plugin bundles for the new installation methods.

   npm run build
   

   Copy code

2. Inspect the imports at the top of the dist/index.js file. You should only see imports from ckeditor5 (not from ckeditor5/src/*) and optionally from other external dependencies.

3. Repeat the above step for the dist/browser/index.es.js file, but this time you should only see imports from ckeditor5 or ckeditor5-premium-features. All other imports, including external dependencies, should be bundled with the plugin.

If you see imports in the second or third step that are not explicitly mentioned, check where the imports come from in the source code and if they have been updated according to the above migration steps. If this is the case and the imports in the generated bundle are still incorrect, please create a new issue in the CKEditor 5 repository.

Once the package is migrated, follow the Build output and integration guide to integrate it with npm, ZIP, or CDN setups.