Skip to content

ckeditor/ckeditor5-package-generator

Repository files navigation

CKEditor 5 Package Generator

CircleCI Coverage Status

This repository follows the mono-repository structure. It contains multiple npm packages.

Table of contents

Packages

Name Version Description
ckeditor5-package-generator npm version The tool for creating CKEditor 5 packages.
@ckeditor/ckeditor5-package-tools npm version Development environment tools for CKEditor 5 packages.

Developing the ckeditor5-package-generator repository

  • Clone the repository: git clone git@github.com:ckeditor/ckeditor5-package-generator.git
  • Install required dependencies: yarn install

Creating a package

To create a new package, call the ckeditor5-package-generator executable file. It requires a single argument which is the package name. It must follow the schema: @scope/ckeditor5-package, where @scope is an owner of the package, and ckeditor5-package is the package name. It must start with the ckeditor5- prefix.

The tool will create a new directory called ckeditor5-package with an example plugin called Package and tools for its development.

To use a local version of the @ckeditor/ckeditor5-package-tools package, use the --dev option when executing the command.

node /path/to/repository/packages/ckeditor5-package-generator <packageName> [--dev] [--use-npm] [--use-yarn] [--name <...>] [--lang <js|ts>] [--verbose]

Options

  • --dev – whether to execute in the development mode. It means that the @ckeditor/ckeditor5-package-tools will not be installed from npm, but from the local file system.
  • --use-npm – use npm to install dependencies in a newly created package.
  • --use-yarn – use yarn to install dependencies in a newly created package.
  • --name – define a class 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.

Developing the package

Available scripts and their modifiers are described in the README.md file of the ckeditor5-package-generator package.

Package metadata

The ckeditor5-metadata.json file contains data of the package that allows for an automated detection of plugins and processing them by external scripts. Information about how this file should be maintained is available in the official guide. Keep in mind that this file has no effect on how the plugin work.

Developing tools in the repository

When creating a new package with the --dev option, the local version of the @ckeditor/ckeditor5-package-tools will be installed instead of its npm version.

However, applying changes in the local repository does not impact an already created package. Hence, you need to create a link between the local repository and the new package.

# The assumption here is your current working directory points to the root directory in the repository.
cd packages/ckeditor5-package-tools
yarn link

# Then, go to the newly created package.
cd /path/to/new/package/ckeditor5-foo
yarn link @ckeditor/ckeditor5-package-tools

Now, the newly created package uses changes from the local repository.

Releasing packages

Changelog

  1. Fetch all changes and switch to the #master branch.
  2. Execute npm run changelog:
  • Scan the logs printed by the tool – search for errors (incorrect changelog entries). Incorrect entries (e.g., ones without the type) are being ignored. You may need to create entries for them manually. This is done directly in CHANGELOG.md (in the root directory). Make sure to verify the proposed version after you modify the changelog.
  • When unsure what has changed in this version of a specific package, use git diff <hash of the previous release> packages/<name>/.

Publishing

After generating the changelog, you are ready for publishing packages.

First, you need to bump their versions:

npm run release:prepare-packages

After bumping versions, you can publish changes:

npm run release:publish-packages

License

The ckeditor5-package-generator tool is available under MIT license.

All packages created with the tool are also available under the MIT license.