Migrating CKEditor 5 from npm to CDN

This guide will help you migrate CKEditor 5 from an NPM-based installation to a CDN-based one. CDN-based installations can simplify the setup process by providing a bundler-agnostic way to lazy initialization of CKEditor 5 scripts and styles injection. It reduces complexity in the project setup.

Prerequisites

If you use frameworks like Laravel, Symfony, or Ruby on Rails, modify the head section in the main layout file and follow the traditional HTML integration to install CKEditor 5.

However, if you use SPA frameworks like React, Angular, Vue.js, or Svelte and do not use official integrations, you may need to follow different steps to migrate CKEditor 5 from npm to CDN. In this case, you can utilize the lazy injection of CKEditor 5 since you cannot directly modify the head section.

Traditional HTML integration

The traditional HTML integration to installing CKEditor 5 involves modification of the HTML head section to include the CKEditor 5 script from the CDN. The editor is then initialized using the window.CKEDITOR global variable.

Step 1: Update your HTML file

First, update your HTML file to include the CKEditor 5 script from the CDN. Add the following script and style sheet tag inside the <head> section of your HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor 5 CDN Example</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/46.1.0/ckeditor5.css">
    <script src="https://cdn.ckeditor.com/ckeditor5/46.1.0/ckeditor5.js"></script>

    <!-- Optionally, add premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/46.1.0/ckeditor5-premium-features.css">
    <script src="https://cdn.ckeditor.com/ckeditor5/46.1.0/ckeditor5-premium-features.js"></script>
</head>
<body>
    <textarea name="content" id="editor"></textarea>
    <script src="app.js"></script>
</body>
</html>

Step 2: Replace CKEditor 5 imports with `window.CKEDITOR`

Since the CKEditor 5 script is now included via the CDN, you can access the ClassicEditor object directly in your JavaScript file using the window.CKEDITOR global variable. It means that import statements are no longer needed and you can remove them from your JavaScript files. Here is an example of migrating the CKEditor 5 initialization code:

Before:

import { ClassicEditor } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector('#editor'), {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        // ... other configuration
    } )
    .catch( error => {
        console.error(error);
    } );

After:

const { ClassicEditor } = window.CKEDITOR;
const { AIAdapter, /* ... other imports */ } = window.CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
    .create( document.querySelector('#editor'), {
        licenseKey: '<YOUR_LICENSE_KEY>',
        // ... other configuration
    } )
    .catch( error => {
        console.error(error);
    } );

Using lazy injection of CKEditor 5

If you prefer to automatically inject the CKEditor 5 script into your HTML file, you can migrate your project using the @ckeditor/ckeditor5-integrations-common package. This package provides a loadCKEditorCloud function that automatically injects the CKEditor 5 scripts and styles into your HTML file. It may be useful when your project uses a bundler like Webpack or Rollup and you cannot modify your head section directly.

Step 1: Install the `@ckeditor/ckeditor5-integrations-common` Package

First, install the @ckeditor/ckeditor5-integrations-common package using the following command:

npm install @ckeditor/ckeditor5-integrations-common

Step 2: Replace CKEditor 5 Imports

If you have any CKEditor 5 imports in your JavaScript files, remove them. For example, remove lines like:

import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

Next, update your JavaScript file to use the loadCKEditorCloud function from the @ckeditor/ckeditor5-integrations-common package. Here is an example of migrating the CKEditor 5 initialization code:

Before:

import { ClassicEditor } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector('#editor') )
    .catch( error => {
        console.error(error);
    } );

After:

import { loadCKEditorCloud } from '@ckeditor/ckeditor5-integrations-common';

const { ClassicEditor } = await loadCKEditorCloud( {
    version: '46.1.0',
} );

Migrating custom plugins

If you are using custom plugins, you need to first adapt these to work with the CDN approach. It will change the way imports and CSS files are handled.

Next, refer to the Loading CDN resources guide to learn about using the loadCKEditorCloud function. This will be needed to include the custom plugin in the CDN configuration of CKEditor 5. By employing these, you can dynamically import the plugin in a way similar to this one:

plugins: {
  CustomPlugin: () => import('./path/to/plugin.umd.js')
}

If your plugin depends on core plugins already loaded via CDN, you can access them through the window.CKEDITOR and window.CKEDITOR_PREMIUM_FEATURES global variables.

Also, loadCKEditorCloud uses caching, so you can call it to dynamically load dependencies. Find more details in the options section of the Loading CDN resources guide.

Conclusion

Following these steps, you successfully migrated CKEditor 5 from an NPM-based installation to a CDN-based installation using Vanilla JS. This approach simplifies the setup process and can help improve the performance of your application by reducing the bundle size.