Installing plugins

    In this guide you can learn how to add plugins to your editor in the two most common scenarios:

    In order to start developing CKEditor 5 you will require:

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

    Adding plugins to existing builds is done through their customization. Editor builds are maintained in their respective GitHub repositories. Therefore, assuming that you want to customize the classic editor build you need to:

    • Clone the build repository.
    • Install the plugin package.
    • Add it to the build configuration.
    • Bundle the build.

    Now, install the plugin package:

    Edit the src/ckeditor.js file to add your plugin to the list of plugins which will be included in the build and to add your feature’s button to the toolbar:

    1. // The editor creator to use.
    2. import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
    4. import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
    5. import UploadAdapter from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
    6. import Autoformat from '@ckeditor/ckeditor5-autoformat/src/autoformat';
    7. import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
    8. import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
    9. import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
    10. import EasyImage from '@ckeditor/ckeditor5-easy-image/src/easyimage';
    11. import Heading from '@ckeditor/ckeditor5-heading/src/heading';
    12. import Image from '@ckeditor/ckeditor5-image/src/image';
    13. import ImageCaption from '@ckeditor/ckeditor5-image/src/imagecaption';
    14. import ImageStyle from '@ckeditor/ckeditor5-image/src/imagestyle';
    15. import ImageToolbar from '@ckeditor/ckeditor5-image/src/imagetoolbar';
    16. import ImageUpload from '@ckeditor/ckeditor5-image/src/imageupload';
    17. import Link from '@ckeditor/ckeditor5-link/src/link';
    18. import List from '@ckeditor/ckeditor5-list/src/list';
    19. import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
    21. import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment';     // <--- ADDED
    23. export default class ClassicEditor extends ClassicEditorBase {}
    25. // Plugins to include in the build.
    26. ClassicEditor.builtinPlugins = [
    27.     Essentials,
    28.     UploadAdapter,
    29.     Autoformat,
    30.     Bold,
    31.     Italic,
    32.     BlockQuote,
    33.     EasyImage,
    34.     Heading,
    35.     Image,
    36.     ImageCaption,
    37.     ImageStyle,
    38.     ImageToolbar,
    39.     ImageUpload,
    40.     List,
    41.     Paragraph,
    42.     Alignment                                                            // <--- ADDED
    43. ];
    45. // Editor configuration.
    46. ClassicEditor.defaultConfig = {
    47.     toolbar: {
    48.         items: [
    49.             'heading',
    50.             '|',
    52.             'bold',
    53.             'italic',
    54.             'link',
    55.             'bulletedList',
    56.             'numberedList',
    57.             'imageUpload',
    58.             'blockQuote',
    59.             'undo',
    60.             'redo'
    61.         ]
    62.     },
    63.     image: {
    64.         toolbar: [
    65.             'imageStyle:full',
    66.             'imageStyle:side',
    67.             '|',
    68.             'imageTextAlternative'
    69.         ]
    70.     },
    71.     // This value must be kept in sync with the language defined in webpack.config.js.
    72.     language: 'en'
    73. };

    Finally, bundle the build:

    You can open the sample/index.html file in your browser to see whether the plugin was installed correctly.

    This was a quick version of how a build can be customized. Read more about in a separate guide.

    If you build the editor from source, then the process of installing a new plugin boils down to these three steps:

    • Installing the plugin package.
    • Adding it to your editor’s configuration.
    • Building your project. For example, if you wish to install the text alignment feature:
    1. npm install --save-dev @ckeditor/ckeditor5-alignment

    Edit the code that initializes the editor:

    1. import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
    2. import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
    3. import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
    4. import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
    5. import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
    7. import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment';     // <--- ADDED
    9. ClassicEditor
    10.     .create( document.querySelector( '#editor' ), {
    11.         plugins: [ Essentials, Paragraph, Bold, Italic, Alignment ],     // <--- MODIFIED
    12.         toolbar: [ 'bold', 'italic', 'alignment' ]                       // <--- MODIFIED
    13.     } )
    14.     .then( editor => {
    15.     } )
    16.     .catch( error => {
    17.         console.error( error.stack );
    18.     } );

    After rebuilding your project, the new feature will be available in the editor.

    One of the possible mistakes is trying to add a plugin in this way to an existing (bundled) editor build. Installing an existing build and then trying to add a plugin to it may not work if that plugin needs to import any of the source editor modules.

    What is the difference between adding a plugin to an editor build and adding a plugin by passing the config.plugins option to the static create() method?

    The first method builds the plugin into the editor class. This means that you can then initialize the editor without passing config.plugins at all and the editor will automatically enable all built-in plugins:

    All this works because a typical src/ckeditor.js module that you can find in every editor build repository (see for example ) looks like this:

    1. import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
    2. import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
    3. import UploadAdapter from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
    5. import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
    6. import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
    7. import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
    8. // ...
    10. export default class ClassicEditor extends ClassicEditorBase {}
    12. ClassicEditor.builtinPlugins = [
    13.     Essentials,
    14.     UploadAdapter,
    15.     Autoformat,
    16.     Bold,
    17.     Italic,
    18.     BlockQuote,
    19.     // ...
    20. ];
    22. ClassicEditor.defaultConfig = {
    23.     toolbar: {
    24.         items: [
    25.             'heading',
    26.             'bold',
    27.             // ...
    28.         ]
    29.     },
    30.     // ...
    31. };

    This code imports the source of the classic editor and extends it with a static builtinPlugins and defaultConfig properties where it defines a set of plugins and configuration to be used by this editor class.

    In this approach, all editor instances created by using this editor build will by default load all these built-in plugins and configuration.

    You can still use the config.removePlugins and options to override the default configuration.

    1. import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
    2. import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
    3. import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
    4. import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
    5. import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
    7. ClassicEditor
    8.     .create( document.querySelector( '#editor' ), {
    9.         plugins: [ Essentials, Paragraph, Bold, Italic ],
    10.         toolbar: [ 'bold', 'italic' ]
    11.     } )
    12.     .then( editor => {
    13.         console.log( 'Editor was initialized', editor );
    14.     } )
    15.     .catch( error => {
    16.         console.error( error.stack );
    17.     } );

    So, in short, both methods use very similar mechanisms. However, adding a plugin through the static builtinPlugins property (which happens in editor builds) lets you automatically enable it in all editor instances created using this editor class, while passing a plugin to will naturally affect only one instance.