title: Custom builds category: builds-development
A build is a simple npm package (usually developed in a Git repository) with a predefined set of dependencies. Out of this repository, distribution files can be generated through the build process.
Some of the reasons for creating custom builds are:
Start with forking one of the official builds (it will serve as the starting point for your custom one) and then clone your fork:
git clone https://github.com/<your-username>/ckeditor5-build-classic.git
To make updating easier you may optionally add the original build repository to your Git remotes:
git remote add upstream https://github.com/ckeditor/ckeditor5-build-classic.git
If you do not want to fork the official build, you can just clone it. However, you will not be able to commit and push your customizations back to [GitHub](https://github.com).
Every build contains the following files:
package.json – The definition of the npm package. It specifies the package name, version, dependencies, license, etc.build-config.js – The configuration of this particular CKEditor 5 build.ckeditor.js – The bundler's "entry file". A CommonJS module which tells the bundler (like webpack) which CKEditor modules should be included in the bundle and what should that bundle export). By default, it is created based on the build configuration but you may also modify it manually.build/* – The directory with ready-to-use bundles. There are two bundles:
build/ckeditor.js.build/ckeditor.compat.js.In order to customize a build you need to:
build-config.js.ckeditor.js and editor bundles in build/*).The easiest way to install missing dependencies is by typing:
npm install --save <package-name>
This will install the package and add it to package.json. You can also edit package.json manually.
Due to a non-deterministic way how npm installs packages, it is recommended to run `rm -rf node_modules && npm install` when in doubt. This will prevent some packages from getting installed more than once in `node_modules/` (which might lead to broken builds).
You can also give [Yarn](https://yarnpkg.com/lang/en/) a try.
If you added or removed dependencies, you will also need to modify the build-config.js file. Based on it the bundler entry file (ckeditor.js) will be created. You can also opt out from automatically creating the entry file and modify ckeditor.js manually, which can be useful in some non-standard cases.
Either way, every plugin that you want to include in the bundle should be included at this stage. You can also change the editor creator and specify the default editor configuration. For instance, your build configuration might look like this:
'use strict';
module.exports = {
editor: '@ckeditor/ckeditor5-editor-classic/src/classic',
moduleName: 'ClassicEditor',
plugins: [
'@ckeditor/ckeditor5-presets/src/essentials',
'@ckeditor/ckeditor5-autoformat/src/autoformat',
'@ckeditor/ckeditor5-basic-styles/src/bold',
'@ckeditor/ckeditor5-basic-styles/src/italic',
'@ckeditor/ckeditor5-heading/src/heading',
'@ckeditor/ckeditor5-link/src/link',
'@ckeditor/ckeditor5-list/src/list',
'@ckeditor/ckeditor5-paragraph/src/paragraph',
'ckeditor5-custom-package/src/customplugin',
'../relative/path/to/some/othercustomplugin'
],
config: {
toolbar: [ 'headings', 'bold', 'italic', 'custombutton' ]
}
};
After you changed the build configuration or updated some dependencies, it is time to rebuild the bundle. This will run a bundler (webpack) with a proper configuration (see webpack.config.js and webpack.compat.config.js).
If you wish to create the bundles based on the build configuration (build-config.js) run:
npm run build
This command will update the entry file (ckeditor.js) and create two bundles – build/ckeditor.js and build/ckeditor.compat.js.
If you want to skip updating the entry file (in case you modified it manually) run:
npm run build-ckeditor
npm run build-ckeditor-compat
You may decide to update your build at any time. Since it is a fork of the official build, you can simply merge the changes that happened meanwhile in that build, using Git commands:
git fetch upstream
git merge upstream/master
You should handle eventual conflicts and verify the merged changes. After that, just follow the previous instructions for creating your build and test it.
It is recommended to run `rm -rf node_modules && npm install` after you fetched changes from the upstream or updated versions of dependencies in `package.json` manually. This will prevent npm from installing packages more than once (which may lead to broken builds).
If you think that your custom builds can be useful to others, it is a great idea to publish them on GitHub and npm. When doing so, just be sure to give them meaningful names that would fit the ckeditor5-build-(the name) pattern, making them easy to find. To avoid conflicts with other existing builds you can use scoped packages.
After your build is out, ping us on Twitter!