Seamless CKEditor 5 Integration in Nuxt3:
A Step-by-Step Guide
Reading Time
13
minutes
published
Aug 12, 2024
share
This article will provide a detailed example of integrating the CKEditor 5 into a Nuxt.js 3 project. Why did the idea for this article arise? The project under development uses a stack of Vue3 + Nuxt.js 3 + PrimeVue. PrimeVue already has a built-in editor, but it works based on Quill. This editor is good for a quick start, but the project required: saving the entered content as HTML (Quill uses its own delta format), as the content needed to be rendered later in a Flutter web application. It was necessary to ensure minimal compatibility with the previous project from which migration was taking place, where CKEditor 4 was used.
Project Start
The project will use node v20.11.0 and npm version 10.2.4
We will conduct the example development in a clean project, which was created using the initialization command according to the official Nuxt documentation.
Now we need to install the core part of the editor. Important! First, it’s necessary to check the available versions for the packages. All packages for the editor (plugins and extensions) should be installed with the same version.
We choose the latest stable version from the available options. In this case, it will be `43.0.0`.
Where:
`@ckeditor/ckeditor5-vue@6.0.0` is the component for integrating the editor
`@ckeditor/ckeditor5-build-classic@43.0.0` is the core build of the editor.
After installing the package versions, they need to be locked. The final `package.json` will look something like this:
Next, let’s create a page that will serve as the main page for our example, where we will later place the editor:
We will fill the `pages/index.vue` page with the simplest content:
Check the functionality by running the server:
Let’s create a component that will wrap the integrated editor:
We fill the `components/rich-editor.vue` component with a placeholder template:
And than we will connect the component to the main template in pages/index.vue:
Connecting the CKEditor
To connect the editor, we need to:
Create an initial editor configuration or use a ready-made build. In our case, we’ll start with a basic build, which we’ll later replace with our own custom build.
Create and connect a plugin to the Nuxt.js project.
Add the created editor configuration to the component that will wrap the editor.
CKEditor 5 will be connected to the project as a plugin. Therefore, we need to create this plugin first:
Let’s create the plugin configuration in `plugins/ckeditor.ts`:
To connect the plugin, we need to edit the project’s configuration file `nuxt.config.ts`:
It’s important to note that in the current project configuration, the option ssr: false is used, which means there's no need to specify in the components where they should be rendered (client or server).
Now, let’s add the current editor build to the previously prepared component components/rich-editor.vue:
Let’s start the server and check:
The editor is ready to use. If the basic functionality is enough for you, then you can stop here.
Notes: when installing new versions of the editor, you should not immediately increase the version of the ckeditor5-vue package, since they may not add support for the latest versions of the editor. If it does not work with the latest stable version, then try to roll back to a lower major version of the package (for example, 7.0.0 → 6.0.0)
CKEditor Configuration
We have connected only the basic editor build, but what if you need to configure the necessary functionality? For this, you can create an additional configuration or more than one.
Information on all possible pluggable functions can be found in the corresponding section of the editor documentation.
To create a new configuration for the editor, we will use the file `utils/custom-editor.ts`:
The location of the configuration file is not strictly defined, it can be placed in a directory convenient for you in accordance with the workflow built-in the project.
Next, you need to install the appropriate plugins that will be responsible for the desired functionality. As noted earlier, plugins must be selected in accordance with the version of the editor you are using. This article considers version `43.0.0`. How to find what needs to be installed? For example, let’s take the quote insertion function. The relevant documentation article describes the operation and connection of the plugin, and the name of the plugin must be found in the project repository:
Let’s install the plugin and several additional packages that will be needed to create our own configuration:
Where:
`@ckeditor/ckeditor5-core@43.0.0` for using types in the configuration
`@ckeditor/ckeditor5-essentials@43.0.0` a set of minimal functions for the editor to work
`@ckeditor/ckeditor5-block-quote@43.0.0` a plugin for connecting quotes
`@ckeditor/ckeditor5-paragraph@43.0.0` a plugin for the ability to create paragraphs in the editor. Important! Without this plugin, you will not be able to type text inside the editor field.
A separate command removes the `@ckeditor/ckeditor5-build-classic` build, since we are setting up our own configuration
File `package.json` after installation:
Add the configuration and installed plugin to the `utils/custom-editor.ts` file:
It is important to note the following in the configuration:
You need to include styles from `ckeditor5.css`
Plugins are imported from the `ckeditor5` package and this method of inclusion appeared in the editor from version `42.0.0`. Before that, another method of importing plugins directly from installed packages was used. Old methods of inclusion can be found in the corresponding sections of the documentation
You need to describe `toolbar` in the configuration, since it will describe the editor’s user interface
Next, add a new configuration to the plugin configuration file `plugins/ckeditor.ts`:
In the wrapper component `components/rich-editor.vue` you have to specify the use of the new configuration:
Let’s launch and check the editor’s work:
Thus, to connect the functionality of interest, it is necessary:
Install the plugin via the package manager
Add the plugin to the configuration
Put the corresponding function on the toolbar
Example CKEditor configuration from the author
Below is an example of an advanced configuration. Installing plugins:
The configuration in the `utils/custom-editor.ts` file with these plugins will look like this:
After connecting the plugins, the editor will look like this:
Additional CKEditor configurations
In addition to the main editor configuration, it is also possible to create as many additional configurations as you like. Why is this necessary? For example, to limit functionality for certain users or to implement an additional field that will include a limited set of functions (for example, formatted headers).
Let’s supplement the configuration file `utils/custom-editor.ts` with a new configuration for the extended input field:
Extending the `plugins/ckeditor.ts` project plugin with a new editor configuration:
Let’s create a new wrapper component for the new field:
Next, we fill the `components/extended-input-field.vue` component:
Add a new component to the page in `pages/index.vue`:
Let’s check the result:
Conclusion
Integrating CKEditor 5 into a Nuxt.js 3 project opens up powerful rich text editing capabilities for your application. By following the step-by-step guide in this article, you’ve learned how to:
Set up a basic Nuxt.js 3 project
Install and configure CKEditor 5
Create a custom build with specific plugins and features
Implement multiple editor configurations for different use cases
The flexibility of CKEditor 5 allows you to tailor the editor to your specific needs, from a full-featured rich text editor to a more constrained input field. This customization ensures that you can provide the right editing experience for your users, whether they need complex formatting options or a simpler interface.
Some key takeaways:
Always ensure plugin versions match your CKEditor core version
Utilize the plugin system to add or remove features as needed
Create multiple editor configurations to suit different parts of your application
Pay attention to toolbar configuration to provide a smooth user experience
As you continue to develop your Nuxt.js application, you can further refine your CKEditor implementation. Consider exploring advanced features like custom plugins, collaborative editing, or integration with your backend for image uploads and content management.
Remember that the CKEditor documentation is an invaluable resource for troubleshooting and discovering new features. As both Nuxt.js and CKEditor evolve, stay updated with the latest versions and best practices to ensure your rich text editing solution remains robust and efficient.
By mastering the integration of CKEditor 5 in your Nuxt.js 3 project, you’ve added a powerful tool to your web development toolkit, enhancing the content creation capabilities of your application.
published
Aug 12, 2024
share
