JavaScript package content
This guide describes the contents of the JavaScript
package generated by the Package Generator.
# Structure of the project
An overview of the project’s directory structure:
├─ lang
│ └─ contexts.json # Entries used for creating translations.
├─ sample
│ ├─ (*) dll.html # The editor initialized using the DLL builds.
│ ├─ index.html # The sample file.
│ └─ ckeditor.js # The editor initialization script.
├─ scripts
│ └─ build-dist.mjs # Script creates `npm` and browser builds for your plugin.
├─ src
│ ├─ pluginname.js # The plugin with example functionality.
│ ├─ index.js # The modules exported by the package.
│ └─ **/*.js # All JavaScript source files should be saved here.
├─ tests
│ ├─ pluginname.js
│ ├─ index.js # Tests for the plugin.
│ └─ **/*.js # All tests should be saved here.
├─ theme
│ ├─ icons
│ │ ├─ ckeditor.svg # The CKEditor 5 icon displayed in the toolbar.
│ │ └─ **/*.svg # All icon files should be saved here.
│ └─ **/*.css # All CSS files should be saved here.
│
├─ .editorconfig # See link below for details.
├─ .eslintrc.cjs # ESLint configuration file.
├─ .gitattributes # See link below for details.
├─ .gitignore # See link below for details.
├─ .stylelintrc # Stylelint configuration file.
├─ ckeditor5-metadata.json # See link below for details.
├─ LICENSE.md # All created packages fall under the MIT license.
├─ package.json # See link below for details.
├─ README.md # Description of your project and usage instructions.
└─ vitest.config.js # Vitest configuration file.
(*) This file is not available if the plugin was generated with the current
value of the --installation-methods
flag.
Guides for developing some of the files:
# Npm scripts
The npm scripts are a convenient way to provide commands in a project. They are defined in the package.json
file and shared with other people contributing to the project. It ensures that the developers use the same commands with the same options (flags).
You can execute all the scripts by running npm run <script>
. Pre-commands and post-commands with matching names will be run for those as well.
The following scripts are available in the package.
# start
Starts an HTTP server with the live-reload mechanism that allows previewing and testing of plugins available in the package.
When the server has been started, the default browser will open the developer sample. You can turn this off by passing the --no-open
option to that command.
You can also define the language that will translate the created editor by specifying the --language [LANG]
option. It defaults to 'en'
.
Examples:
# Starts the server and opens the browser.
npm run start
# Disable auto-opening the browser.
npm run start -- --no-open
# Create the editor with the interface in German.
npm run start -- --language=de
# test
Allows executing unit tests for the package specified in the tests/
directory using Vitest testing framework. To check the code coverage, add the --coverage
modifier. See other CLI flags in Vitest.
Examples:
# Execute tests.
npm run test
# Generate code coverage report after each change in the sources.
npm run test -- --coverage --watch
# test:debug
Allows executing unit tests for the package specified in the tests/
directory using Vitest testing framework with the possibility of debugging them. Once Vitest starts, it will stop execution and wait for you to open developer tools that can connect to Node.js inspector.
Examples:
# Execute tests in the debug mode.
npm run test:debug
# lint
Runs ESLint, which analyzes the code (all *.js
files) to quickly find problems.
Examples:
# Execute ESLint.
npm run lint
# stylelint
Similar to the lint
task, stylelint
analyzes the CSS code (*.css
files in the theme/
directory) in the package.
Examples:
# Execute stylelint.
npm run stylelint
# build:dist
Creates npm and browser builds of your plugin. These builds can be added to the editor by following the Configuring CKEditor 5 features guide.
Examples:
# Builds the `npm` and browser files thats are ready to publish.
npm run build:dist
# dll:build
(*)
This script is not available if the plugin was generated with the current
value of the --installation-methods
flag.
Creates a DLL-compatible package build which can be loaded into an editor using DLL builds.
Examples:
# Build the DLL file that is ready to publish.
npm run dll:build
# Build the DLL file and listen to changes in its sources.
npm run dll:build -- --watch
# dll:serve
(*)
This script is not available if the plugin was generated with the current
value of the --installation-methods
flag.
Creates a simple HTTP server (without the live-reload mechanism) that allows verifying whether the DLL build of the package is compatible with the CKEditor 5 DLL builds.
Examples:
# Starts the HTTP server and opens the browser.
npm run dll:serve
You can run npm run dll:build -- --watch
and npm run dll:serve
in two separate command terminals. That way, after you save your changes and reload the page, the content will update.
# translations:synchronize
Synchronizes translation messages (arguments of the t()
function) by performing the following steps:
- Collect all translation messages from the package by finding
t()
calls in source files. - Perform the validations to detect if translation context is valid. It checks whether the provided values do not interfere with the values specified in the
@ckeditor/ckeditor5-core
package, and there is no missing, unused or duplicated context entries. - If there are no validation errors, update all translation files (
*.po
files) to be in sync with the context file:- unused translation entries are removed,
- missing translation entries are added with empty string as the message translation,
- missing translation files are created for languages that do not have own
*.po
file yet.
The task may end with an error if one of the following conditions is met:
- Found the
Unused context
error – entries specified in thelang/contexts.json
file are not used in source files. They should be removed. - Found the
Duplicated contex
error – some of the entries are duplicated. Consider removing them from thelang/contexts.json
file, or rewriting them. - Found the
Missing context
error – entries specified in source files are not described in thelang/contexts.json
file. They should be added.
Examples:
npm run translations:synchronize
# translations:validate
Peforms only validation steps described in translations:synchronize
script without modifying any files. It only checks the correctness of the context file against the t()
function calls.
Examples:
npm run translations:validate
# prepare
Npm supports some special life cycle scripts. They allow automatically performing operations in certain situations:
prepare
– Triggers during package creation and before publishing.
This script creates npm and browser builds of your plugin.
If during the package creation the --installation-methods
flag value was set to current
the script creates npm and browser build only without CKEditor 5’s legacy installation methods.
# How to change ESLint configuration
To change the ESLint configuration, edit the .eslintrc.js file. It is also a good idea to check out the ESLint documentation.
# Why are the predefined ESLint rules recommended
To make CKEditor 5 plugins compatible with each other, we needed to introduce certain limitations when importing files from packages. To learn more, visit the DLL guide and see a detailed explanation about the limitations.
# Translations
Packages created by this tool, just like the entirety of the CKEditor 5 ecosystem, include support for localization. If you wish to include translations for your package, visit the dedicated translation guide to learn more.
The package generator provides a synchronization tool to help preparing files needed for translation into other languages. We recommend the following flow when dealing with translations:
- Call
npm run translations:synchronize
– Prepare the translation files in all supported languages. It creates files for each language inlang/translations
directory in PO format. Each*.po
file contains empty entry for every message found in thelang/contexts.json
file. - Provide translations to messages in the generated
lang/translations/*.po
files.
# Reporting issues
If you found a problem with CKEditor 5 or the package generator, report an issue:
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.