guideEditor bundle

# Overview

An “editor bundle” is the source code of a pre-configured and ready-to-use CKEditor 5 editor, which is minified and merged into a single file. Such a properly prepared editor is required to use the document storage as well as import and export features.

A correctly built editor must be uploaded to CKEditor Cloud Services because it is used to convert operations that are in the collaboration session to data (HTML, Markdown, text etc. depending on your editor configuration). Without the uploaded editor CKEditor Cloud Services will not be able to convert the document to a form that looks the same as the collaborating user sees.

The same editor bundle should also be used by the collaborating users on your website.

Whenever you change something in your editor bundle or its configuration, you should re-upload it to CKEditor Cloud Services. It prevents the use of different versions of the editor bundle on your website and on the CKEditor Cloud Services server.

Otherwise, if the changes you make to the editor or its configuration affect the appearance or formatting of the document, the document data will look different than on your website. Even worse, some issues with converting the user operations on the CKEditor Cloud Services server may appear in such scenario.

# Building the editor bundle

You can build your editor just like it is done in the official CKEditor 5 documentation.

However, for your editor to be used by CKEditor Cloud Services, it must fulfill certain requirements, as explained below.

# Requirements

The following conditions must be met for an editor bundle to be supported by CKEditor Cloud Services.

Adding a plugin by passing the config.plugins option to the static create() method is not possible because your editor config is sent to CKEditor Cloud Services in a JSON format with your editor bundle. Objects or functions that can be Plugins cannot be sent in this format.

As such, the only way to add plugins to the editor is to use the static builtinPlugins property.

Using the CKEditorCS name is compulsory because CKEditor Cloud Services can only use your editor under the CKEditorCS class name.

# Uploading the editor bundle

If you have already built your editor, you must upload it to the server together with the editor configuration. The editor upload process requires the use of the POST /editors method described in the Editors REST API section.

Two required parameters are passed to the body of this method:

  • bundle – The code of your minified editor in a form of a string.

Before you upload your editor to the CKEditor Cloud Services server, make sure it was built in accordance with the requirements mentioned above.

  • config – This is the editor configuration that you will also use on your website. See the Editor configuration section below for more details.

# Editor configuration

CKEditor 5 configuration sent to the CKEditor Cloud Services server should be identical to the editor configuration used on your website. The editor configuration must be prepared in the JSON format, with the settings for config.cloudServices and the required bundleVersion property inside.

{
  "cloudServices": {
    "bundleVersion": "unique_editor_bundle_version"
  }
}

Note that bundleVersion is a property that acts as a unique build identifier.

It is assumed that whenever you change something in your bundle or its configuration, you should re-upload it to CKEditor Cloud Services with a new bundleVersion.

The bundleVersion property is required in the configuration used on your website and in the configuration uploaded to CKEditor Cloud Services.

# Editor upload request body example

The following is an example for the body of the editor upload request:

{
  "bundle": "content string of the editor bundle",
  "config": {
    "cloudServices": {
      "bundleVersion": "unique_editor_bundle_version"
    }
  }
}

Remember that the editor bundle that you uploaded is only available within the environment to which it was assigned. If you use the same editor for different environments, you must upload it separately for each of them.

# Example

Check an example of creating an editor bundle in Node.js.