Skip to content

Building

Jump to bottom Edit New page
Piotrek Koszuliński edited this page Apr 20, 2018 · 11 revisions

⚠⚠ ⚠⚠ ⚠⚠

This wiki served in the early days of CKEditor 5 development and can be severely outdated.

Refer to the official CKEditor 5 documentation for up-to-date information.




CKEditor 5 is built out of multiple npm packages from which the ckeditor5 repository centralizes the environment. See the Architecture Overview and Repositories for more information on these subjects.

There are several building scenarios, depending on how the CKEditor 5 is being developed or integrated into some other project. However, all scenarios share one specific trait – the editor files are scattered around those multiple repositories and hence need to be gathered together in a simple directory structure. This process is called building.

The common scenarios are:

  • Building CKEditor from source.
  • Developing CKEditor packages.
  • Integrating CKEditor into another project.

Scenarios

Building CKEditor from Source

In this scenario the developer:

  1. clones the ckeditor5 repository,
  2. installs CKEditor packages by modifying the package.json file or running npm install ckeditor5-<package-name>.
  3. runs npm install to install all dependencies.

This means that all CKEditor 5 packages and their dependencies (including other CKEditor 5 packages) will be available in the ckeditor5/node_modules/ directory.

In order to build the editor it's enough to run:

gulp build

Read more about building CKEditor from source.

Deduping Dependencies

Prior to version 3 npm would create a deep structure where dependency's dependencies are located inside its own directory. E.g. if ckeditor5-link required ckeditor5-attribute-style, we would have ckeditor5/node_modules/ckeditor5-link/node_modules/ckeditor5-attribute-style. The process of flattening the tree is called deduping and since version 3 npm dedupes packages automatically.

However, if there's a conflict between dependency versions (e.g. ckeditor5-link requires ckeditor5-attribute-style in version 5.1.0 while ckeditor5-basic-style requires ckeditor5-attribute-style in version 6.0.0), then npm cannot dedupe packages, so ckeditor5-link and ckeditor5-basic-style would require their own copies of ckeditor-attribute-style. This situation is usually well handled in Node.js environment, but we want to avoid it in the various browser environments for which CKEditor 5 will be built (AMD, ES6 modules, standalone build, etc.). Therefore, once the builder discovers that some package wasn't deduped, it will throw errors (see ckeditor/ckeditor5#76).

Developing CKEditor Packages

In this scenario the developer cloned the ckeditor5 repository and then switched one or more CKEditor 5 packages to the development mode. This means that those packages will contain their own dependencies, because those cannot be deduped. Hence, the builder must in this case look for all the packages one level deeper in the directory structure.

This scenario makes also validating the conflicts between dependency versions harder as simply checking if the tree was fully deduped isn't enough.

Read more about the development workflow.

Integrating CKEditor into Another Project

In this scenario the developer works on a project which needs to include CKEditor. This developer:

  1. Added ckeditor5 and required ckeditor5-* packages to his/her package.json (in dependencies section).
  2. Run npm install.
  3. Run the builder available in the ckeditor5 package (this can be done by running gulp --cwd node_modules/ckeditor5/ build or adding CKEditor's build task to the developer project's gulpfile.js; we can also expose other ways to run the builder in the future).

The builder must now take CKEditor 5 packages from the ckeditor5's parent directory. If the structure wasn't fully deduped it means that there was a version conflict.

Build Result

The directory structure of the build is highly simplified comparing to the initial state. The build is put in the dist/<format>/ directory where format is one of supported module system name – amd (AMD), cjs (CommonJS) or esnext (ES6 modules).

Inside the build directory the following structure is created:

  • ckeditor.js – the API entry point (ckeditor5/ckeditor.js)
  • ckeditor5/
    • *.* – files from ckeditor5/src/*.*
    • <package-name>/* – files from the ckeditor5-<package-name>/src/* package
  • tests/
    • *.* – files from ckeditor5/tests/*.*
    • <package-name>/* – files from the ckeditor5-<package-name>/tests/* package

Module Paths

The directory structure of a build reflects relative paths between JavaScript modules kept in these files. For instance, if a module kept in ckeditor5/link/link.js wanted to import ckeditor5/core/treemodel/element.js it would need to use the following import statement:

import Element from '../core/treemodel/element.js';

A different scheme is used for paths from test files to the source code. Due to Bender.js way of serving files (the paths may change on a specific occasions - e.g. when running a job) the test files must use absolute paths starting from the build directory. E.g.:

import Element from '/ckeditor5/core/treemodel/element.js';

Similarly, when a test file needs to import some test util:

import coreTestUtils from '/tests/core/_utils/utils.js';
Add a custom footer
Add a custom sidebar
Clone this wiki locally