Installing plugins

CKEditor 5 plugins, responsible for various features, are distributed through npm packages. We implemented them in a modular way. It means a single plugin may contain multiple JavaScript files. Do not hesitate and explore available CKEditor 5 features – they are waiting for you to install them!

# Requirements

To enrich the CKEditor 5 by installing plugins, you will require:

• Node.js 18.0.0+
• npm 5.7.1+ (note: some npm 5+ versions were known to cause problems, especially with deduplicating packages; upgrade npm when in doubt)

If you are here looking for a way to install plugins, there is a chance you have the CKEditor already installed. But if you do not, you have two options: create a custom build with an online builder or integrate the editor from the source.

# Adding a plugin to an editor

You can start adding plugins if you are in a directory with the CKEditor 5 build or the root folder of your application if you are integrating the editor from the source. Every plugin has its corresponding npm package. To install any plugin, you can use this template in a terminal:

npm install <plugin-name>

# Installing a package

Let’s say you want to install the alignment package. It adds text alignment functionality to your editor. You can install it using the following command:

npm install @ckeditor/ckeditor5-alignment

The command will install the package and add it to package.json. You can also edit package.json manually. All packages (excluding @ckeditor/ckeditor5-dev-*) must have the same version as the base editor package.

# Updating the editor’s configuration

To add a plugin to your editor, you need to follow three steps:

1. Import the installed package in the file with the CKEditor configuration.
2. Add the imported plugin to the list of plugins. There are two ways to achieve that: using the builtinPlugins property or passing a plugin to the create() method. Adding a plugin through the property lets you automatically enable it in all editor instances using this editor class. Passing the plugin to the method will affect only one instance.
3. Configure the toolbar if the installed plugin requires UI.

// <path-to-your-build>/src/ckeditor.ts or file containing editor configuration if you are integrating an editor from source.

// The editor creator to use.
import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';

import { Alignment } from '@ckeditor/ckeditor5-alignment';  // Importing the package.
import { Autoformat } from '@ckeditor/ckeditor5-autoformat';
import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles';
import { BlockQuote } from '@ckeditor/ckeditor5-block-quote';
import { CloudServices } from '@ckeditor/ckeditor5-cloud-services';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { Heading } from '@ckeditor/ckeditor5-heading';
import {
    Image,
    ImageCaption,
    ImageStyle,
    ImageToolbar,
    ImageUpload
} from '@ckeditor/ckeditor5-image';
import { Indent } from '@ckeditor/ckeditor5-indent';
import { Link } from '@ckeditor/ckeditor5-link';
import { List } from '@ckeditor/ckeditor5-list';
import { MediaEmbed } from '@ckeditor/ckeditor5-media-embed';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';
import { PasteFromOffice } from '@ckeditor/ckeditor5-paste-from-office';
import { Table, TableToolbar } from '@ckeditor/ckeditor5-table';
import { TextTransformation } from '@ckeditor/ckeditor5-typing';



class Editor extends ClassicEditor {
    public static override builtinPlugins = [
        Alignment,  // Adding the package to the list of plugins.
        Autoformat,
        BlockQuote,
        Bold,
        CloudServices,
        Essentials,
        Heading,
        Image,
        ImageCaption,
        ImageStyle,
        ImageToolbar,
        ImageUpload,
        Indent,
        Italic,
        Link,
        List,
        MediaEmbed,
        Paragraph,
        PasteFromOffice,
        Table,
        TableToolbar,
        TextTransformation
    ];

    // Editor configuration.
    public static override defaultConfig = {
        toolbar: {
            items: [
                'alignment',  // Displaying the proper UI element in the toolbar.
                'heading',
                '|',
                'bold',
                'italic',
                'link',
                'bulletedList',
                'numberedList',
                '|',
                'outdent',
                'indent',
                '|',
                'imageUpload',
                'blockQuote',
                'insertTable',
                'mediaEmbed',
                'undo',
                'redo'
            ]
        },
        language: 'en',
        image: {
            toolbar: [
                'imageTextAlternative',
                'toggleImageCaption',
                'imageStyle:inline',
                'imageStyle:block',
                'imageStyle:side'
            ]
        },
        table: {
            contentToolbar: [
                'tableColumn',
                'tableRow',
                'mergeTableCells'
            ]
        }
    };
}

export default Editor;

# Building an editor

If you are using builds you need to rebuild your editor. To do that, call the webpack executable in a folder containing your build:

./node_modules/.bin/webpack --mode development

You can also install webpack-cli globally (using npm install -g) and run it via a globally available webpack.

Alternatively, you can add it as an npm script:

// package.json

"scripts": {
    "build": "webpack --mode development"
}

And use it with:

npm run build

If you are integrating an editor from the source into your application, this step should be handled by build scripts used in your project.

# Adding an unofficial JavaScript plugin

The CKEditor 5 is a TypeScript project, and all plugins provided by CKEditor 5 also use TypeScript. However, there are ways to use JavaScript packages with the editor.

# Community types

Even if the package you want to use is in JavaScript, there is a chance there are already types you can use. Definitely Typed is a central repository of TypeScript definitions for non-typed npm packages. To install community types for your JavaScript package, try the following command:

npm install --save-dev @types/<package-name>

If you successfully installed those types, there is nothing more to do. You should no longer see TypeScript compiler errors, and your project should be ready to build.

# Custom declarations

If you create a custom plugin, community types will not be available. In that case, you need to add your custom definitions.

First, create a declaration file .d.ts in your project. For example, you can place it in types/index.d.ts. Then inside the file, define the module as shown in the example below.

// index.d.ts

declare module 'path' { // Module name.
  export function normalize( p: string ): string; // API exposed by the module.
  export function join( ...paths: any[] ): string;
}

Finally, make sure the TypeScript compiler is aware of your declarations. Put the path to the directory with your file inside the include array.

// tsconfig.json

{
    "include": [ "./src", "./types" ],
    "compilerOptions": {
        // Compiler options.
        // ...
    }
    // More options.
    // ...
}

# Suppressing errors

If there are no community types and creating declarations is not an option, there is still a way to build a TypeScript project with a JavaScript package. Just add a reserved TypeScript comment above the JavaScript package.

// @ts-ignore
import { foo } from 'javascript-package';

This comment suppresses all errors that originate from the following line.