Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@_sh/strapi-plugin-ckeditor) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

CKEditor 5 for Strapi

Integrates CKEditor 5 into your Strapi project as a fully customizable custom field. (Unofficial integration)

✨ Features

Media library integration
Responsive images support
Strapi theme switching support
Supports custom styles for the editor
Supports i18n and different UI translations
Allows custom editor configrations
Plugins extensibility

🔧 Installation

Add the package to your Strapi application:

npm install @_sh/strapi-plugin-ckeditor

yarn add @_sh/strapi-plugin-ckeditor

Then build the app:

npm run build

yarn build

✍️ Usage

Default preset:

⚙️ Configuration

It is highly recommended to explore the official CKEditor5 documentation and the Strapi Custom Field API

To display content from external sources, such as images or videos, in your admin panel, you need to configure your middlewares.js file. Check the official documentation for details.

The plugin configuration should be defined in your-app/config/ckeditor.js|ts

By default, the plugin provides one preset, which can be modified in the config file.

You can also add new presets in the config file.

The plugin exposes all CKEditor packages to the global variable SH_CKE.

The config file must define a function called CKEConfig that returns the configuration object.

The structure of the configuration object is as follows:

{
    dontMergePresets:bool,
    dontMergeTheme:bool,
    presets:{
        default:{
            field:{...},
            styles:string,
            editorConfig:{...},
        },
        ...
    }
    theme:{
        common:string,
        light:string,
        dark:string,
        additional:string,
    }
}

Every preset in the presets object contains three properties:

field (object) Registers this configuration version in the Admin panel.
styles (string) Styles applied to the editor in this version.
editorConfig (object) The CKEditor configuration.

The theme object is used to modify the default global theme of the plugin. It contains four properties:

common (string) Styles applied to the editor to ensure proper appearance of the input.
light (string) Styles applied to the editor when Strapi is in light mode.
dark (string) Styles applied to the editor when Strapi is in dark mode.
additional (string) Additional styles to further enhance the editors appearance.

By default, everything defined in the user’s configuration is merged with the default configuration object. These two properties allow you to prevent this behavior:

dontMergePresets (bool)
dontMergeTheme (bool)

Since Strapi uses i18n for translation, the ignorei18n property is added to the editorConfig.language object. This property allows you to manually set the content language, bypassing i18n. The language object looks like this:

language:{
    ignorei18n (bool),
    ui (string),
    content (string)
}

The language determination follows this logic:

Plugin UI language: language.ui -> preferred language -> 'en'
Content language: ignorei18n ? language.content : i18n -> language.ui

Example of adding a new editor configuration:

ckeditor.js

const CKEConfig = () => ({
    presets:{
        myCustomPreset:{
            field: {
                key: "myCustomPreset",
                value: "myCustomPreset",
                metadatas: {
                    intlLabel: {
                        id: "ckeditor5.preset.myCustomPreset.label",
                        defaultMessage: "My custom preset",
                    },
                },
            },
            editorConfig:{
                plugins: [
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                heading: {
                    options: [
                        { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                        { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                        { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                        { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                        { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                    ]
                },
                image: {
                    toolbar: [
                        'imageStyle:inline',
                        'imageStyle:block',
                        'imageStyle:side',
                        '|',
                        'toggleImageCaption',
                        'imageTextAlternative'
                    ]
                },
                table: {
                    contentToolbar: [
                        'tableColumn',
                        'tableRow',
                        'mergeTableCells',
                        '|',
                        'toggleTableCaption'
                    ]
                }
            }
        }
    }
})

Example of changing buttons, modifying the plugin list, and adding styles in the default preset:

ckeditor.js

const CKEConfig = () => ({
    presets:{
        default:{
            styles:`
                --ck-focus-ring:3px dashed #5CB176;

                .ck.ck-content.ck-editor__editable {
                  &.ck-focused:not(.ck-editor__nested-editable) {
                    border: var(--ck-focus-ring) !important;
                  }
                }
                .ck.ck-content.ck-editor__editable.ck-rounded-corners.ck-editor__editable_inline.ck-blurred{
                  min-height: 400px;
                  max-height: 400px;
                }
                .ck.ck-content.ck-editor__editable.ck-rounded-corners.ck-editor__editable_inline.ck-focused{
                  min-height: 400px;
                  max-height: 1700px;
                }
            `,
            editorConfig:{
                plugins: [
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ]
            }
        }
    }
})

📂 Default preset: admin/src/Input/presets/default.js

📂 Default theme: admin/src/Input/theme

Adding plugins

Your plugin must be available in the global.

Example of adding the Timestamp plugin:

Create the plugin:

// your-app/src/admin/timestamp.js

class Timestamp extends SH_CKE.Plugin {
    init() {
        const editor = this.editor;
        // The button must be registered among the UI components of the editor
        // to be displayed in the toolbar.
        editor.ui.componentFactory.add( 'timestamp', () => {
            // The button will be an instance of ButtonView.
            const button = new SH_CKE.ButtonView();

            button.set( {
                label: 'Timestamp',
                withText: true
            } );

            // Execute a callback function when the button is clicked.
            button.on( 'execute', () => {
                const now = new Date();

                // Change the model using the model writer.
                editor.model.change( writer => {

                    // Insert the text at the user's current position.
                    editor.model.insertContent( writer.createText( now.toString() ) );
                } );
            } );

            return button;
        } );
    }
}

globalThis.Timestamp = Timestamp;

Import the plugin:

// your-app/src/admin/app.js

import './timestamp.js'

const config = {};

const bootstrap = (app) => {};

export default {
  config,
  bootstrap,
};

Add the new plugin to your preset:

ckeditor.js

// your-app/config/ckeditor.js

const CKEConfig = () => ({
    presets: {
        myCustomPreset:{
            field: {
                key: "myCustomPreset",
                value: "myCustomPreset",
                metadatas: {
                    intlLabel: {
                    id: "ckeditor5.preset.myCustomPreset.label",
                    defaultMessage: "My custom preset",
                    },
                },
            },
            editorConfig:{
                plugins: [
                    Timestamp,
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'timestamp',
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                
                // ...
            }
        },
  }
})

Then rebuild the application:

npm run build

yarn build

Alternatively, you can define your plugin like this:

ckeditor.js

const CKEConfig = () => {
  class Timestamp extends SH_CKE.Plugin {
    init() {
      const editor = this.editor;
      // The button must be registered among the UI components of the editor
      // to be displayed in the toolbar.
      editor.ui.componentFactory.add("timestamp", () => {
        // The button will be an instance of ButtonView.
        const button = new SH_CKE.ButtonView();

        button.set({
          label: "Timestamp",
          withText: true,
        });

        // Execute a callback function when the button is clicked.
        button.on("execute", () => {
          const now = new Date();

          // Change the model using the model writer.
          editor.model.change((writer) => {
            // Insert the text at the user's current position.
            editor.model.insertContent(writer.createText(now.toString()));
          });
        });

        return button;
      });
    }
  }

  return {
    presets: {
        myCustomPreset:{
          field: {
            key: "myCustomPreset",
            value: "myCustomPreset",
            metadatas: {
              intlLabel: {
                id: "ckeditor5.preset.myCustomPreset.label",
                defaultMessage: "My custom preset",
              },
            },
          },
            editorConfig:{
                plugins: [
                    Timestamp,
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'timestamp',
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                
                ...
            }
        },
  }
}

🛠 Contributing

This section covers how to configure your environment if you want to contribute to this package.

To start making changes to the plugin, you first need to install the Strapi infrastructure on top of the plugin repository:

npx create-strapi-app --quickstart strapi
cd strapi

By default, Strapi does not create a plugins folder, so we need to create it:

mkdir -p src/plugins

Now we should clone this repository so we can work on it.

git clone git@github.com:nshenderov/strapi-plugin-ckeditor.git src/plugins/strapi-plugin-ckeditor

Add an entry inside the ./package.json file so we won't need to use yarn inside the plugin itself:

"workspaces": ["./src/plugins/strapi-plugin-ckeditor"]

Install dependencies:

yarn install

Now we need to register the plugin so Strapi can use it. To do that, we need to create the ./config/plugins.js file (if it doesn't already exist) and add an entry to it:

module.exports = ({ env }) => ({
  ckeditor5: {
    enabled: true,
    resolve: "./src/plugins/strapi-plugin-ckeditor"
  },
});

Rebuild the project and start the server:

yarn build
yarn develop

✈️ Migration

From v2 to v3

The default editor configurations (toolbar, toolbarBalloon, blockBalloon) have been removed and now there is only one preset by default. You will need to update your fields in the Content-Type Builder.
Config file extension has changed from .txt to .js or .ts
Configuration object properties have been renamed:
- configsOverwrite -> dontMergePresets
- themeOverwrite -> dontMergeTheme
- configs -> presets
From v3 instead of globalThis.CKEditorConfig = {..}, the config file must define a function called CKEConfig that returns the configuration object.

Example of the new configuration file:

ckeditor.js

const CKEConfig = () => ({
    presets:{
        myCustomPreset:{
            field: {
                key: "myCustomPreset",
                value: "myCustomPreset",
                metadatas: {
                    intlLabel: {
                        id: "ckeditor5.preset.myCustomPreset.label",
                        defaultMessage: "My custom preset",
                    },
                },
            },
            editorConfig:{
                plugins: [
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                heading: {
                    options: [
                        { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                        { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                        { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                        { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                        { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                    ]
                },
                image: {
                    toolbar: [
                        'imageStyle:inline',
                        'imageStyle:block',
                        'imageStyle:side',
                        '|',
                        'toggleImageCaption',
                        'imageTextAlternative'
                    ]
                },
                table: {
                    contentToolbar: [
                        'tableColumn',
                        'tableRow',
                        'mergeTableCells',
                        '|',
                        'toggleTableCaption'
                    ]
                }
            }
        }
    }
})

From v1 to v2

You will need to update Strapi to version v4.4.x for plugin v2.0.x, or to v4.13.0+ for v2.1.x.
Starting with v2, the plugin uses the Custom Field API, so you'll need to manually update your schema.
The plugin configuration should be defined in /config/ckeditor.txt from v2 onward. Please refer to the v2 configuration guide for details.

⚠️ Requirements

Strapi >= 4.13.0 < 5.0.0

Node >=18.0.0 <=20.x.x