Using the package generator
The ckeditor5-package-generator
is a tool for developers. It creates a working package with the development environment that allows writing new custom plugins for CKEditor 5.
# Quick start
To create a new package without installing the tool, simply execute the following command:
npx ckeditor5-package-generator <packageName> [--use-npm] [--use-yarn] [--installation-methods <current|current-and-legacy>] [--plugin-name <...>] [--lang <js|ts>] [--global-name <...>] [--verbose]
The <packageName>
argument is required and must obey these rules:
- The provided name must match the schema:
@scope/ckeditor5-*
, where @scope is the owner of the package. - The package name must start with the
ckeditor5-
prefix. - Allowed characters are numbers (
0-9
), lowercase letters (a-z
) and symbols:-
.
_
.
As a result of executing the command, a new directory with a package in it will be created. The directory’s name will be equal to the specified package name without the @scope
part, and it will contain an example plugin and the development environment.
Available modifiers for the command are:
--use-npm
– usenpm
to install dependencies in the newly created package.--use-yarn
– useyarn
to install dependencies in the newly created package.--global-name
– define a global name of the package to be used in the UMD build.--plugin-name
– define the plugin name to be different from the package name.--lang
– (values:js
|ts
) choose whether the created package should use JavaScript or TypeScript. If omitted, the script will ask the user to choose manually.--verbose
– (alias:-v
) print additional logs about the current executed task.--installation-methods
– (values:current
|current-and-legacy
) choose which installation methods of CKEditor 5 do you want to support? If omitted, the script will ask the user to choose manually.
# Choosing the method
Currently, a package can be generated in one of two modes of supported installation methods for CKEditor 5 :
- The package will only support the current installation methods if the value for the
--installation-methods
flag is set tocurrent
. This approach makes it easier to create CKEditor 5 plugin at the cost of not supporting the old installation methods. - The package generator creates bundles for both the current installation methods and legacy installation methods if the value for the
--installation-methods
flag is set tocurrent-and-legacy
.
# Using the package
After successfully creating a directory with the new package, enter it by executing the following command:
# Assuming that your package was created with `ckeditor5-foo` as its name.
cd ckeditor5-foo
Then, run the test environment for the plugin by executing the following command:
npm run start
Now the plugin can be seen within the example editor.
You can check out what is available inside your package depending on the language you used:
# Migration
If you have used the ckeditor5-package-generator
(version 1.1.0
or lower) to generate and develop your own plugins for CKEditor 5 and now you want to migrate to the newest installations methods used by CKEditor 5 please visit the Migrating CKEditor 5 to new installation methods guide. You will find an instruction there that will guide you step by step through all things that need to be changed.
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.