Creating a Custom Build for CKEditor 5

By: Steve Elliott

OVERVIEW

As far as WYSIWYG editors go, CKEditor 5 is a nice one. It comes with 5 variations, but I especially like the new Balloon Block Editor. However, if you aren't satisfied with the basic package, you'll need to create a custom build. That's a good thing, because then you're only going to build it with the features you want, instead of being bloated with a bunch of features you're never going to use. 

If you don't want to perform the build yourself, CKEditor does offer an online tool at https://ckeditor.com/ckeditor-5/online-builder that will perform a build for you.

If you're like me and would rather do it yourself and benefit from the flexibility that provides, keep reading. For your reference, the Custom Build documentation can be seen at: https://ckeditor.com/docs/ckeditor5/latest/builds/guides/development/custom-builds.html. To me, it seems the documentation skips over some basic steps (for developers not familiar with node/git), so some developers who just want to add a feature to an editor and build it themselves may be left scratching their heads. So, I put this post together to help out anyone that may need a more detailed walk-through, plus give you some experience with node and git.

REQUIREMENTS

As mentioned in the documentation, you're going to need the following (which I'm going to go into more detail about):

  • Node.js 6.9.0+
  • npm 4+
  • Git

LET'S GET STARTED

Installing Node.js and npm

If you already have Node.js and Node Package Manager (npm) installed, you can move to the next section. If you aren't sure if you have Node.js or npm installed, the first thing you'll need to do is check by opening Command Prompt and entering "node -v".  When you enter it, it will look something like:

C:\Users\steve>node -v

This should go without saying, but your username will appear where it says "steve".

This should respond with the version that's installed. It'll look something like:

C:\Users\steve>node -v
v12.14.1

If you did get a version response similar to that (you may see a different version), then also check to see that npm by entering "npm -v".

C:\Users\steve>npm -v

It should also respond with a version number.

If either of these responds saying it is not recognized as an internal or external command, operable program or batch file, then node/npm are not installed and you'll need to install them.

To install them, visit the following website to perform the installation: https://nodejs.org

Before I list the steps, I'm basically going to go through the steps of their installer and accept all the default settings. It's that simple. If Windows asks you if the app should be allowed to make changes to your device, click Yes.

  1. The first thing you'll do after landing on their home page is select which version you want. Out of habit, I typically will choose the Long Term Support (LTS) version, so I'm choosing the first one, which is 12.14.1 LTS at the time of this post.
  2. After clicking it, you'll likely get a pop-up alert asking you if you want to Run it or Save it. I typically just click Run, but you could save it and go double click the downloaded file to run it.
  3. After the installation wizard pops up, there's basically just some Welcome text. Click the Next button to move forward with the installation.
  4. End-User License Agreement - On this step, read the license agreement if you want, click the checkbox to accept the terms, then click the Next button.
  5. Destination Folder - This should already have filled in a default folder location, which should be fine, so just click the Next button.
  6. Custom Setup - This step shows a tree with various features that will be installed. It's okay to leave the default settings as well, so just click the Next button.
  7. Tools for Native Modules - The step offers a checkbox to install Python and Visual Studio Build Tools. Unless you know you want or need these tools, you can leave it unchecked for now. You could always run the installation again later to change the way features are installed, then check the box on the last step at that time.
    • The reason I say all of this, is I selected that check box while installing it on another computer (so I could write out these steps) and the install failed. I ended up uninstalling it and reinstalling without checking that box on the last step.

Now you should have node and npm installed. If you open Command Prompt and check for versions again, you should get a response with them now. If you don't, try closing Command Prompt and opening it back up. Mine didn't notice it until I closed it and reopened it.

Installing Git

If you were to try running a Git command prior to installing it, you'd see "'git' is not recognized as an internal or external command, operable program or batch file."

To install Git, visit https://git-scm.com/download/win and the install will likely initiate automatically. If so, just click Run in the alert to begin. If it asks you if you want to allow the app to make changes to your device, click Yes. 

  1. After the installation wizard opens, you'll see the license. Read it if you want, then click the Next button.
  2. The next step shows the destination folder. You can leave the default settings and just click the Next button.
  3. This step allows you to change which components you want to install. I didn't make any changes and just clicked the Next button.
  4. This next step creates a Start Menu folder to place the programs shortcuts in. The default is fine, so just click the Next button.
  5. In this step you can change the default editor for git if you want, but I'm just left the default, then click the Next button.
  6. This next step asks how would you like to use Git from the command line? I'm leaving the recommended default (which is "Git from the command line and also from 3rd-part software"), since I'm going to use Command Prompt.
  7. This step allows you to choose an HTTPS transport backend. I'm just leaving the default setting, then click the Next button.
  8. The next step allows you to select how Git should treat line endings. I'm leaving the default "Checkout Windows-style, commit Unix-style line endings", then click the Next button.
  9. On this step, you can choose the terminal emulator to use. I'm actually going to change this to use Windows' default console window, then click Next.
  10. I just left the default settings on this last step and clicked the Install button.
  11. After the installation process has finished, the installer will display a "Setup has finished installing Git" message. Click the Next button to exit the installer.

Now, close down Command Prompt if you have it open and reopen it. Then enter "git --version" at the prompt

C:\Users\steve>git --version

and you should get a response with the version that looks similar to

C:\Users\steve>git --version
git version 2.25.0.windows.1

Cloning & Building CKEditor

Now that you have Node.js, npm, and Git installed, you can begin the process of creating your custom build. The first thing you need to do is clone a CKEditor from GitHub. Go back to Command Prompt and you should be in your Users directory (i.e. mine is C:\Users\steve). 

You can create a different folder somewhere else if you want, but you'll have to factor that in during all the rest of the steps.

Now we want to create a directory that we're going to close the CKEditor 5 files into. Enter "mkdir CKEditor5" into Command Prompt

C:\Users\steve>mkdir CKEditor5

then hit the Enter key. There shouldn't be any response. If you prefer, you can also navigate to your folder (i.e. C:\Users\steve) in Windows Explorer and create the folder there. Name it CKEditor5.

Now enter "cd CKEditor5" and hit enter, then it should take you into that directory, which will look like this

C:\Users\steve>cd CKEditor5

C:\Users\steve\CKEditor5>

At this point, you're ready to clone the CKEditor into your directory. You can choose another version of CKEditor5 if you want, but I'm going to work with the Balloon Block version. They sort of mention this in the CKEditor 5 documentation, but their example shows forking it. You don't really need to do that. All you need to do is clone a stable version

C:\Users\steve\CKEditor5>git clone -b stable https://github.com/ckeditor/ckeditor5-build-balloon-block.git

After you hit the Enter key, it'll clone the files and should have the CKEditor 5 files copied into your folder when it's done.

Now, navigate into the newly created folder by changing directories again. The new folder that was created is called "ckeditor5-build-balloon-block", so you'll need to enter "cd ckeditor5-build-balloon-block" into Command Prompt

C:\Users\steve\CKEditor5>cd ckeditor5-build-balloon-block

Next, you'll need to install dependencies. In Command Prompt, enter "npm install"

C:\Users\steve\CKEditor5\ckeditor5-build-balloon-block>npm install

This may take a few minutes, since it needs to install several files that were defined in the build's package.json file. Once it's done, you're nearly ready to customize and build your new editor.

If you want to see the build process run before making any changes, you can now enter "npm run build" into Command Prompt and it will build the editor.

C:\Users\steve\CKEditor5\ckeditor5-build-balloon-block>npm run build

Once the build process finishes, you can verify it by opening Windows Explorer and navigating to this "ckeditor5-build-balloon-block" directory, then enter the "build" folder. If you look at the "Date modified" for the ckeditor.js file, you'll see that it is now the date and time that you ran the build. After you make your changes to the source files and run the build again, this will be the ckeditor.js file that you'll copy and place into your website project.

Since this post has already turned into a pretty long one, I'm just going to show how to make a simple addition to the editor. If you download the CKEditor 5 Balloon Block editor at https://ckeditor.com/ckeditor-5/download/ and install it into your website, you'll notice it doesn't have an underline feature by default. For example, when you highlight some text, the editor will display a popup that lets you set the text to Bold, Italic, or create a Link.

If you have any problems installing the default editor into your website, a Quick Start guide is available at: https://ckeditor.com/docs/ckeditor5/latest/builds/guides/quick-start.html. 

To add the Underline feature, you'll need to open the source ckeditor file from within the new folder you just downloaded a little bit ago (ckeditor5-build-balloon-block/src/ckeditor.js). Open this in your favorite code editor (Visual Studio 2019, right?) and add the following line to the import directives, just under the "import Italic from...." directive.

import Underline from '@ckeditor/ckeditor5-basic-styles/src/underline';

Now scroll down to the next section and add "Underline" to the plugins for BalloonEditor.builtinPlugins. Just add it after "Italic," and don't forget to add the comma after Underline! ;)

BalloonEditor.builtinPlugins = [
	Essentials,
	UploadAdapter,
	Autoformat,
	BlockToolbar,
	CodeBlock,
	Bold,
	Italic,
	BlockQuote,
	CKFinder,
	EasyImage,
	Heading,
	Image,
	ImageCaption,
	ImageStyle,
	ImageToolbar,
	ImageUpload,
	Indent,
	Link,
	List,
	MediaEmbed,
	Paragraph,
	PasteFromOffice,
	Table,
	TableToolbar
];

Now, you just need to add the reference to the editor configuration. Scroll down to the section that defines the value for BalloonEditor.defaultConfig and find the toolbar node, then the items node within it. Create a new line after 'italic' and add 'underline'. It should now look like:

...
toolbar: {
    items: [
        'bold',
        'italic',
        'underline',
        'link'
    ]
},
...

Now save your edited ckeditor.js source file, and rebuild it by entering the following command again (be sure to do it from the right directory, as mentioned here)

C:\Users\steve\CKEditor5\ckeditor5-build-balloon-block>npm run build

Finally, all you have to do is copy the newly built file at ckeditor5-build-balloon-block/build/ckeditor.js and add it to your website project! And as I mentioned earlier, if you need helping using CKEditor 5 in your website, there's a quick start guide at: https://ckeditor.com/docs/ckeditor5/latest/builds/guides/quick-start.html.

If you found this helpful, please be sure to use the social links at the top of this post to share it with your friends.