Sign up (with export icon)

Editor bundle

Show the table of contents
Tip

Let an AI coding agent set up the editor bundle for you. The official ckeditor-bundle skill adds scripts that build the editor bundle from the editor of your application. The scripts also check the bundle with test data and upload it. Install the CKEditor 5 skills:

npx skills add ckeditor/skills
Copy code

Then ask your agent, for example: “Set up the editor bundle for CKEditor Cloud Services”. Review the changes before you commit them. See the Using CKEditor 5 with AI coding agents guide for setup options and supported agents.

Overview

Copy link

An editor bundle is the source code of a pre-configured and ready-to-use CKEditor 5, which is minified and built as a single file. To use the Server-side Editor API, document storage, import and export, or connection optimization features, you need to upload an exact copy of the editor file from your application to the CKEditor Cloud Services server.

CKEditor Cloud Services uses your editor bundle to convert operations in the collaboration session into data. Thanks to this, CKEditor Cloud Services can ensure data consistency between users and the stored data. Furthermore, if your editor bundle is using some custom plugins that can output some custom data, it will be then properly handled by CKEditor Cloud Services.

Whenever you change something in your editor bundle or its configuration, you should update it on the CKEditor Cloud Services server, too. If the users use different versions of the editor than the one uploaded to the server, it may lead to data loss or even editor crashes.

Features that require the editor bundle

Copy link
Feature group Requires editor bundle
Collaboration Import / Export Yes
Documents Import / Export / Copy Yes
Document Storage Yes
Server-side Editor API Yes
Connection optimization Yes
Coauthor Yes
Revision History No
Real-Time Collaboration No
Comments No
Track Changes (Suggestions) No
Users No
Webhooks No (but webhook events emitted by bundle-requiring features inherit that requirement)

Building the editor bundle

Copy link

First, you need to create an editor bundle and upload it to CKEditor Cloud Services. The upload request with the bundle, its configuration, and the test data must be smaller than 10 MB. You can use any bundler, but the bundle must meet these requirements:

  • It is one JavaScript file that runs as a classic script, for example a UMD build. CKEditor Cloud Services cannot load an ES module.
  • It sets the CKEditorCS global to the editor class itself, not to an object with the exports of the entry file.
  • The editor class lists all plugins in builtinPlugins. CKEditor Cloud Services does not use the config.plugins option.
  • Your application can use plugins that send network requests or use DOM elements outside the editor, but CKEditor Cloud Services must not run them. CKEditor Cloud Services blocks the network requests of the editor during document conversions. Remove such plugins with the removePlugins option of the upload, as the Custom plugins section of the Vite guide shows.

Read more about creating the bundle in the following guides:

Uploading the editor bundle

Copy link

If you have already built your editor that meets the requirements, you can upload it to CKEditor Cloud Services together with the editor configuration. The editor upload process requires the use of the POST /editors method from the Cloud Services REST API.

Every request made to the CKEditor Cloud Services REST API needs to have additional headers: X-CS-Timestamp and X-CS-Signature. Refer to the request signature guide for more details.

Three parameters are passed to the body of this method:

  • bundle – The code of your minified editor passed as a string.
  • config – This is the editor configuration that will be used by the editor in CKEditor Cloud Services. This should be the same config as used by the editor in your application, especially when it can alter the data output.
  • test_data – This is the real document content generated by the editor you upload to the CKEditor Cloud Services server. It helps to detect if any of your custom plugins modify the document content incorrectly or if an invalid configuration has been passed. This parameter is optional but it is highly recommended to use it. You should make sure that your test data has been created using all the custom plugins you have implemented. Take the data from editor.getData( { trim: 'none' } ) and do not change it, because CKEditor Cloud Services compares it with the editor output exactly. Refer to the Testing the editor bundle with test data guide for more details.

The body of the upload request should look like this:

{
	"bundle": "the content of editor bundle file",
	"config": {
		"cloudServices": {
			"bundleVersion": "unique_editor_bundle_version"
		},
		"removePlugins": [ "myCustomAutoSavePlugin" ],
		... other config options
	},
	"test_data": "<p>example output from your editor</p>"
}
Copy code

The bundleVersion property inside the config.cloudServices object is required.

Note

Remember that the uploaded editor bundle 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.

Editor configuration

Copy link

The bundleVersion property set during an upload acts as a unique build identifier. It tells CKEditor Cloud Services which editor should be used when a user starts the collaboration session. You need to make sure that the editor configuration in your application also has the bundleVersion property and its value matches the editor uploaded to the CKEditor Cloud Services server. An example editor configuration with set bundleVersion looks like this:

return CKEditorCS.create( {
	cloudServices: {
		tokenUrl: 'TOKEN_URL',
		uploadUrl: 'UPLOAD_URL',
		webSocketUrl: 'WEBSOCKET_URL',
		bundleVersion: 'editor-1.0.0'
	},
	collaboration: {
		channelId: 'CHANNEL_ID'
	},
	toolbar: [
		// Toolbar items
	],
	// Other config options
} );
Copy code
Note

The editor configuration uploaded to the CKEditor Cloud Services server should be in JSON format. Therefore, in some cases, the config object needs to be modified before sending:

  • properties of particular plugins that require DOM elements should be set to null or left out. Do not send the DOM elements themselves, because JSON.stringify() turns them into empty objects, which can stop the upload,
  • regex values in General HTML Support configuration should be converted to strings, e.g. "/.*/".

Multi-root editor builds

Copy link

For multi-root editor builds, an upload request body requires an additional is_multi_root_editor field set to true. The field indicates that the uploaded editor is a multi-root build. Additionally, the test_data property is expected to be a stringified JSON structure where the keys are the root names and the values are the HTML content for particular roots.

If you use the attributes of the roots, give example values for each root in the editor configuration. Since CKEditor 5 v48, the attributes are in the roots.<rootName>.modelAttributes option. Earlier versions use the legacy rootsAttributes option. The test data must contain each root of the configuration. Refer to the Multi-root editors section of the test data guide for the rules.

{
	"bundle": "the content of a multi-root editor bundle file",
	"config": {
		"cloudServices": {
			"bundleVersion": "unique_multiroot_editor_bundle_version"
		},
		"removePlugins": [
			"myCustomAutoSavePlugin"
		],
		"roots": {
			"header": {
				"modelAttributes": {
					"order": 1
				}
			},
			"footer": {
				"modelAttributes": {
					"order": 2
				}
			}
		},
		... other config options
	},
	"test_data": "{\"header\":\"<p>Multi-root document header.</p>\",\"footer\":\"<p>Multi-root document footer.</p>\"}",
	"is_multi_root_editor": true
}
Copy code

Example

Copy link

Follow this example to learn how to properly upload the editor bundle to CKEditor Cloud Services. This example is using Node.js and npm, hence it is required to have these tools installed. It also assumes that you have already built the editor bundle. This example will continue using the files from the previous example.

  1. In your terminal, use cd to get into the extracted folder and install the axios package with the npm i axios command.

  2. Create a new upload.js file inside the extracted folder with the following content:

const crypto = require( 'crypto' );
const fs = require( 'fs' );
const path = require( 'path' );
const axios = require( 'axios' );

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';

const apiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/editors/`;
const editorBundle = fs.readFileSync( path.resolve( './dist/editor.bundle.js' ) );

const body = {
	bundle: editorBundle.toString(),
	config: {
		cloudServices: {
			bundleVersion: 'editor-1.0.0' // Set a unique name for the uploaded bundle
		},
		toolbar: [
			// Toolbar items
		],
		// Other config options
	}
};

const CSTimestamp = Date.now();
const axiosConfig = {
	headers: {
		'X-CS-Timestamp': CSTimestamp,
		'X-CS-Signature': generateSignature( apiSecret, 'POST', apiEndpoint, CSTimestamp, body )
	}
};

axios.post( apiEndpoint, body, axiosConfig )
	.then( response => {
		console.log ( response.status );
	} ).catch( error => {
		console.log( error.message );
		console.log( error.response.data );
	} );

function generateSignature( apiSecret, method, uri, timestamp, body ) {
	const url = new URL( uri );
	const path = url.pathname + url.search;
	const hmac = crypto.createHmac( 'SHA256', apiSecret );

	hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

	if ( body ) {
		hmac.update( Buffer.from( JSON.stringify( body ) ) );
	}

	return hmac.digest( 'hex' );
}
Copy code

Run the above code with the node upload.js command.

You should see the 201 status code in your console. You can run node upload.js once again to make sure that the bundle is already uploaded. In this case, you will get a 409 error with message Editor editor-1.0.0 already exists.

Updating the editor bundle

Copy link

As shown in the example above, it is not possible to overwrite an editor bundle on the CKEditor Cloud Services server. You may, however, encounter situations where you need to rebuild your editor, for example when you add a new plugin, update CKEditor 5 version or fix a bug in your custom plugin. You should follow these steps to start using a new editor bundle:

  1. Rebuild your editor with the necessary changes to the configuration or plugins.
  2. Upload the new editor bundle with the bundleVersion value being new and unique for your environment.
  3. Update the bundleVersion in the editor configuration in your application to match the new value from step 2.
  4. Wait for the active collaboration sessions to be removed automatically or remove them manually using the DELETE /collaborations/{document_id} from the CKEditor Cloud Services REST API.
  5. Open the document in your new editor.

A collaboration session initiated with certain bundleVersion can be opened only by editors with the same bundleVersion value. Because of this you can not connect to the previously edited documents with the new editor, without reinitializing such collaboration session (steps 4 and 5).

This rule also applies to the first upload of a bundle. A session that started without a bundle version does not accept an editor with a bundle version. A session that started with a bundle version does not accept an editor without one. Such an editor fails with the realtimecollaborationclient-init-connection-failed error, and the error details say: Incompatible bundle version or engine version detected. Thus, the sessions that are open when you add the bundle version to your application reject the new editor. The new editor can connect after these sessions end or after you remove them.

While users are connected to a session, the DELETE /collaborations/{document_id} request fails with HTTP 409 and the Session <document_id> is not empty. message. A closed browser tab can count as a connected user for some time. To remove the session anyway, add the force=true query parameter. Then CKEditor Cloud Services disconnects the users, and their editors become read-only without an error message. Tell the users before you remove an active session. If document storage is on, CKEditor Cloud Services saves the content of the session in the storage.

If you use document storage, set the bundleVersion in every editor of your application from the first upload on. After the storage saves a document with a bundle version, an editor without a bundle version cannot open this document. It fails with an error such as Editor 49.0.0 not found. Without a bundle version, CKEditor Cloud Services looks for a bundle with the version of CKEditor 5, and no bundle has this version.

Note

To ensure data consistency you should update the editor bundle on CKEditor Cloud Services every time there is a change in your editor. This is especially important when the changes are related to the conversions or the data outputs.