CKEditor Ecosystem Documentation
Search
Contribute to this guide
Home/CKEditor 5/Framework

guideTypeScript package content

This guide describes the contents of the TypeScript package generated by the Package Generator. The transition of the CKEditor 5 codebase to TypeScript is still in progress and hence some errors might occur. If you encounter one, report it.

# 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.ts          # The editor initialization script.
├─ src
│  ├─ pluginname.ts        # The plugin with example functionality.
│  ├─ augmentation.ts      # Type augmentations for the `@ckeditor/ckeditor5-core` module.
│  ├─ index.ts             # The modules exported by the package when using the DLL builds.
│  └─ **/*.ts              # All TypeScript source files should be saved here.
├─ tests
│  ├─ pluginname.ts
│  ├─ index.ts             # Tests for the plugin.
│  └─ **/*.ts              # 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.
├─ typings
│  └─ **/*.d.ts            # Files containing type definitions.
│
├─ .editorconfig           # See link below for details.
├─ .eslintrc.js            # 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.
├─ tsconfig.json           # General TypeScript configuration.
├─ tsconfig.release.json   # Override for options from above file during release process.
└─ README.md               # Description of your project and usage instructions.

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. The command accepts the following modifiers:

  • --coverage – Creates the code coverage report.
  • --watch – Observes the source files (the command does not end after executing tests).
  • --source-map – Generates source maps of the sources.
  • --verbose – Prints additional webpack logs.

Examples:

# Execute tests.
npm run test

# Generate code coverage report after each change in the sources.
npm run test -- --coverage --test

# lint

Runs ESLint, which analyzes the code (all *.ts 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

# dll:build

Creates a DLL-compatible package build that 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

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:collect

Collects translation messages (arguments of the t() function) and context files. Then validates whether the provided values do not interfere with the values specified in the @ckeditor/ckeditor5-core package.

The task may end with an error if one of the following conditions is met:

  • The Unused context error is found – Entries specified in the lang/contexts.json file are not used in source files. They should be removed.
  • The Context is duplicated for the id error is found – Some of the entries are duplicated. Consider removing them from the lang/contexts.json file, or rewrite them.
  • The Context for the message id is missing error is found – Entries specified in the source files are not described in the lang/contexts.json file. They should be added.

Examples:

npm run translations:collect

# translations:download

Downloads translations from the Transifex server. Depending on users’ activity in the project, it creates translation files used for building the editor.

The task requires passing an organization and project names. Usually, it matches the following format: https://www.transifex.com/[ORGANIZATION]/[PROJECT].

To avoid passing these options every time the command calls for it, you can store it in package.json, next to the ckeditor5-package-tools translations:download command.

Examples:

npm run translations:download -- --organization [ORGANIZATION] --project [PROJECT]

# translations:upload

Uploads translation messages onto the Transifex server. It allows for the creation of translations into other languages by users using the Transifex platform.

The task requires passing an organization and project names. Usually, it matches the following format: https://www.transifex.com/[ORGANIZATION]/[PROJECT].

To avoid passing these options every time the command calls for it, you can store it in package.json, next to the ckeditor5-package-tools translations:upload command.

Examples:

npm run translations:upload -- --organization [ORGANIZATION] --project [PROJECT]

# prepare, prepublishOnly and postpublish

Npm supports some special life cycle scripts. They allow automatically performing operations in certain situations:

  • prepare – Triggers during package creation and before publishing.
  • prepublishOnly – Triggers only before publishing.
  • postpublish – Triggers after publishing.

Scripts in this package ensure that a DLL-compatible package build is available after the creation of the package, and that correct files are published:

  • DLL-compatible package build.
  • TypeScript files compiled to JavaScript, along with their type definitions exported.
  • The main field in package.json points to a .js file.

It also ensures that cleanup is performed afterward:

  • Compiled TypeScript files are removed, as they clutter the src directory.
  • The main field in package.json reverts to pointing to a .ts file.

# ts:build and ts:clear

These scripts compile TypeScript and remove the compiled files. They are used in the aforementioned life cycle scripts, and there is no need to call them manually.

# 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.

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 full support for localization. If you wish to include translations for your package, visit the dedicated translation guide to learn more.

The package generator provides several tools for handling translations in the created package. We recommend the following flow when dealing with translations:

  1. Call npm run translations:download – Download the latest version of translations.
    • If there are changes in the lang/translations/* files, commit them as they represent new or updated translation files.
  2. Call npm run translations:collect – Verify whether contexts are up-to-date.
  3. Call npm run translations:upload – Upload new translations.
  4. Call npm run translations:download – If new contexts were uploaded, it updates the en.po file in the package. Do not forget to commit the change.

# Reporting issues

If you found a problem with CKEditor 5 or the package generator, report an issue: