12 min.

Create CKEditor 5 custom build

This guide outlines the process of creating a custom CKEditor 5 build that will work with React, Angular and Vue

This post focuses on creating a custom build of CKEditor 5, assuming you have already integrated a standard build into your application. If you haven't yet integrated a standard build, please refer to existing posts that explain how to incorporate the classic build into various JavaScript frameworks.



How to create a custom build of CKEditor 5


Upon integrating CKEditor into your app, you might find it lacking in basic functionalities, such as alignment or font color options, making the basic build somewhat limited. The primary method to enhance its capabilities is through the addition of new plugins, which necessitates the creation of a custom build. This process can be challenging for many developers.


The CKEditor team has introduced an online builder as a partial solution, which facilitates the creation of a custom build quickly. However, this approach has a significant drawback for production use: builds created via the online builder cannot be updated through Git, preventing you from tracking updates made by the CKEditor authors.


Therefore, it's recommended not to rely solely on the online builder for creating your build. This guide will demonstrate how to link your custom build with the official production branch, with occasional references to the online builder for assistance.



Choosing the editor type


The initial step is to decide on the type of editor you require. CKEditor 5 offers five official builds:


  • Classic
  • Inline
  • Balloon
  • Balloon Block
  • Decoupled Document


If you're uncertain about which build suits your needs, the online builder is a helpful resource for exploration. For now, select an editor type or opt for the classic build, which meets most users' needs. This choice is primarily about the editor's appearance and functionality, not its extensibility through plugins.



CKEditor 5 custom build editor types




Forking the Official Repository


After choosing an editor type, visit the official GitHub repository and navigate to the packages folder, which contains all official plugins and builds. If you've chosen the classic build, for example, fork the repository containing ckeditor5-build-classic. Initially, you must fork the entire framework.



git clone <your-forked-repo.git>



Then, navigate to the framework's root folder to isolate your chosen editor type, such as ckeditor5-build-classic, by changing to the specific build directory. It's crucial to work within this directory when customizing your build. Before making any modifications, create and switch to a new branch, named, for example, mycustombuild.



 cd ./packages/ckeditor5-build-classic


All the subsequent changes of the forked repo will be done in this folder and it's super important that you stick with this folder anytime working on your build. Before making any changes remember to create and checkout into your branch named for example mycustombuild. Then you can start making customisations.



cd ./packages/ckeditor5-build-classic
git checkout -b mycustombuild



Adding Plugins


To discover available plugins and their integration, utilize the official CKEditor 5 online builder. This tool lets you select plugins and generates a custom build. After creating a build with the online builder, locate the ckeditor.js file in the src folder of the downloaded build. Copy all import statements from this file to your local forked repository, register the plugins, and add them to the toolbar. For instance, to include the Alignment plugin, add the following lines to your ckeditor.js file and install the plugin via npm or yarn:



import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment.js';

ClassicEditor.builtinPlugins = [
    // other plugins

ClassicEditor.defaultConfig = {
    toolbar: {
        items: [
            // other toolbar items



npm install @ckeditor/ckeditor5-alignment



Repeat these steps for any additional plugins you wish to include. Feel free to make other modifications, such as removing default packages or adding custom plugins or buttons, before finalizing your changes. Once completed, install all dependencies specified in package.json with:



npm install



Generating Your Custom Build


To create your custom build, execute the following command. This generates a build folder containing essential files, essentially your entire customized editor.



npm run build



Next, navigate to the application where you intend to use your newly created custom build. Assuming you're already utilizing a CKEditor build there, simply replace the ckeditor.js file from your forked repository's build version with the corresponding file in the node_modules directory of your target application.


This method directly replaces the official build's content, which works until the next project package update. During such updates, npm or Yarn will overwrite the modified content with the original. To avoid this, consider creating your own npm package for installation and updates, preserving your custom changes.


After verifying everything functions correctly, commit and push your changes:



git add .
git commit -m "Added alignment plugin"
git push origin mycustombuild



How to use the CKEditor 5 custom build


To use your custom build within your application, it must be installed in node_modules. There are two approaches to achieve this without overwriting your edits, both requiring focus on the specific package/build folder, not the entire forked framework.



Local Installation


For a quick but less maintainable solution, suitable for individual developers, copy the custom build files into your app (outside node_modules). Then, locally install it via npm by specifying the folder path:



npm install /path_to_your_buid_files



Afterward, reinstall npm dependencies:



npm install



Your custom build can now be imported using the name registered in package.json.



Creating an NPM Package


For broader benefits like ease of maintenance and better collaboration, create your npm package. After setting up your npm account, navigate to the CKEditor package folder where modifications were made, log in to NPM, and adjust package.json to reflect your npm username:



npm login



In package.json, change the name value to "@your-npm-name/your-custom-build-name". After successful login, publish your custom build:



  "name": "@your-npm-name/your-custom-build-name",


npm publish --access=public



In your project, install your custom build with:



npm install @your-npm-name/your-custom-build-name



Replace the standard build import in your project (e.g., import ClassicEditor from '@ckeditor/ckeditor5-build-classic') with your custom build (e.g., import ClassicEditor from '@your-npm-name/your-custom-build-name').



How to Update Your Custom Builds


To stay updated with the official CKEditor 5 framework, add an upstream remote pointing to the official repository and merge updates from the stable or master branch into your custom branch:



git remote add upstream https://github.com/ckeditor/ckeditor5.git
git fetch upstream
git merge upstream/stable



Handle any merge conflicts and rebuild your updated version:



npm run build



Commit the changes to your fork and optionally publish the updated version on npm. Update your application's npm packages to receive the new custom build version:



npm update



Utilizing a Pre-built Custom Build


For backend-focused applications where package size is not a concern, consider using a pre-built custom build with all available free plugins, installable via npm:


npm install --save @blowstack/ckeditor5-full-free-build



When using SSR frameworks, ensure JavaScript DOM API calls (e.g., window or document) are client-side. Vue.js users with SSR can utilize a Nuxt.js-specific CKEditor 5 custom build with all free plugins:



npm install --save @blowstack/ckeditor-nuxt