-
Notifications
You must be signed in to change notification settings - Fork 12
Packages
⚠⚠ ⚠⚠ ⚠⚠
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.
Packages are the main building block of CKEditor 5. They let the developers organize their code into components, so other developers can then easily install and reuse them.
npm.js was originally introduced as package manager for Node.js. After a couple of years of a market fragmentation it became the JavaScript package manager, the leading solution for all types of JavaScript related projects – both client and server side. Actually, the differentiation between client and server side code faded thanks to Node.js (significant part of CKEditor 5 code base will be able to run on the client and server). Hence, we decided to adopt npm.js as CKEditor's package manager.
The scenarios how CKEditor can be integrated into your project were explained in the Building – Scenarios chapter.
In this article we assume that you're creating your own fork of CKEditor or developing a new CKEditor 5 package as this is the most popular use case at this stage.
CKEditor 5 packages are available through npm.js. To install them into a clone of the ckeditor5 repository, execute the following in the command line:
npm install --save ckeditor5-<package-name>The --save option will instruct npm to include the plugin inside the dependencies block of the package.json file. This will let you save the configuration of your workspace and let other developers you cooperate with to install all the packages by simply running npm install.
Each package should be coded in a dedicated environment, ideally using Git and GitHub.
To unify all different package projects and to make the build process simpler, the following conventions should be adopted.
To simplify the task of bootstraping a new package the gulp create-package task was introduced. Read more about the Development Workflow.
The package project should be based on the gulp create-package task which provides a basic folder structure and configuration. This raises the overall quality of the code by giving a standard format to it.
- src/ - Contains all files required by the package.
- tests/ - Plugin-specific tests.
- package.json - Other than common meta information, it contains the package's full name, its version and dependencies (usually pointing to other packages). The builder may use this file in the future.
Additionally:
- dev/ – Contains Gulp tasks and other development related resources.
- Various "dotfiles" (.gitignore, .jshintrc and .jscsrc, etc.) – Configuration.
- CHANGES.md, CONTRIBUTING.md, LICENSE.md, README.md – Basic package documentation.
Packages should use the following naming convention:
ckeditor5-<package-name>
... where <package-name> is the unique name of the package.
Few conventions are recommended:
- Packages containing creators:
ckeditor5-creator-<creator-name>. The creator module should be defined insrc/<creator-name>.js. - Packages containing UI components:
ckeditor5-ui-<component-or-library-name>. - Packages containing themes:
ckeditor5-theme-<theme-name>.
While building the content of packages is copied to the dist/<build-format>/ directory. The original paths are transformed in order to simplify and unify them. Read more about the build result and module paths.
Packages are the main building blocks of the editor. They can contain multiple types of files – JavaScript modules, themes (presumably LESS files), graphical resources, etc.
- A single package can contain multiple JavaScript modules (each kept in a separate file).
- Some of those modules can be plugins. The rest of the modules are tools, base classes and other basic components which can be used by other modules. A package can contain no plugins, making it a library.
- A plugin implements a feature, creator or a theme.
It's usually recommended that a single package defines only a single type of plugin (if any). So a package containing a creator is a creator package. Package containing features should not contain themes and creators. Etc.