Гайд - импортируем CKEditor 5 в Laravel 10 как модуль node.js⁠⁠

Всем привет!

Уже давно настала эра WYSIWYG - редакторов текстов, и при написании наших веб проектов мы конечно же стараемся их использовать по максимуму.

Один из таких редакторов ну просто с сумасшедше-огромной функциональностью - это небезызвестный CKEditor, который недавно (шучу, давно уже) зарелизился замечательной 5-й версией.

Ее мы сегодня и будем импортировать в наш проект на Laravel 10. Скриншотик (и пасхалочка, кто знает тот поймет) внизу.

Как обычно есть 2 пути - простой и сложный.

Простой - это просто прописать в шаблоне

<script src="https://cdn.ckeditor.com/ckeditor5/40.0.0/classic/ckeditor.js"></script>

И активировать его на textarea через ClassicEditor.create().

Но есть нюанс.... что если авторы решат уйти из РФ и ограничит доступ? Или же РКН решит что "ты не пройдешь!" и ... ты не пройдешь. Нужно любить всех своих пользователей, а не заставлять их расчехлять VPN потому что на сайте не работает редактор.

Да и мы ведь серьезный проект пишем! Нам нужно свое! Да еще и желательно с кастомным билдом под наши задачи!

По этому мы пойдем по второму пути - сложному, который делится еще на два.

Назовем их "следовать инструкциям" и "догадаться самим".

Но перед тем как начать - нам нужно собрать кастомный билд с нужными нами модулями и настройками. Что можно спокойно сделать на сайте. Я использовал билд на базе ClassicEditor, выбрал нужные мне модули в том числе и модуль watchdog на будущее (сейчас активировать его в коде я его конечно-же не буду). В общем, качаем билд и распаковываем его в "Новая папка (3)" на рабочке. Он нам понадобится, но несколько позже.

Следуем инструкциям.

По инструкции на сайте мы берем скачанный билд, копируем его в папку с проектом в директорию public\assets\ckeditor5, импортируем .js файл в blade шаблон и так-же активируем его через EditorWatchdog() или CreateEditor(). Легко и просто, и в принципе все гайды в интернете по интеграции в Laravel пишут нам что так делать правильно.

Но нас то не обманешь! У нас серьезный проект! И ведь действительно, вдруг нам потом понадобится модуль, который мы не добавили в наш билд? Пересобирать заново? Да ну его! По этому мы пойдем своим путем! Поехали!

Догадываемся сами

К нашему счастью в Laravel встроен замечательнейший инструмент под названием Node.js, который мы и будем использовать. И не только его.

Установка

Идем консолькой в папку с нашим проектом и запускаем (не забудь включить vpn)

npm install --save @ckeditor/ckeditor5-build-classic

Сразу нам устанавливается множество зависимостей, однако наш любимый Laravel 10 этот модуль сразу не увидит. Для того чтобы это исправить нам нужно сделать еще кое-что. Поехали интегрировать.

Интеграция

Нам нужно чтобы наш Laravel увидел CKEditor, да собирал его под наши нужды "на лету". Для этого мы будем использовать vite, благо он идет в составе Laravel. У авторов CKEditor для него есть отдельный модуль с названием @ckeditor/vite-plugin-ckeditor5, его и будем использовать. Также нам понадобится модуль @ckeditor/ckeditor5-theme-lark.

Снова консоль, пишем:

npm install --save @ckeditor/vite-plugin-ckeditor5

npm install --save @ckeditor/ckeditor5-theme-lark

Пока ждем установку - наливаем кофе.

Далее ищем в корне нашего проекта файл vite.config.js и вносим в него следующие строки как показано на скриншоте (слева - старый файл, справа - внесенные изменения)

import { createRequire } from 'node:module';
const require = createRequire( import.meta.url );

import ckeditor5 from '@ckeditor/vite-plugin-ckeditor5';

ckeditor5( { theme: require.resolve( '@ckeditor/ckeditor5-theme-lark' ) } ),

Конфигурируем

Помните ту конфигурацию, что мы делали на сайте CKE? Она то нам сейчас и понадобится.

Открываем Новую папку (3) и в подпапке src находим файл ckeditor.ts. Это файл с настройками нашего билда. Копируем его в папку с проектом, в директорию resources/js.
Также из папки samples копируем style.css в resources/css.
И дополнительно создаем файлик editor.js - его мы и будем встраивать в наш шаблон.

Содержимое editor.js

import ClassicEditor from './ckeditor';

ClassicEditor.Editor
// Note that you do not have to specify the plugin and toolbar configuration — using defaults from the build.
.create( document.querySelector( '#editor' ), {
language: 'ru',
removePlugins: [
'MediaEmbedToolbar'
]
})
.then( editor => {
console.log( 'Editor was initialized', editor );
} )
.catch( error => {
console.error( error.stack );
} );

Для наблюдательных - я специально не использовал watchdog здесь. Импортировать его я планирую потом.

Дальше нам нужно загрузить недостающие модули.

Открываем редактором ckeditor.ts и видим вверху множество импортов.

Открываем папку "node_modules/@ckeditor" внутри проекта и ищем недостающие модули. Если такие есть - устанавливаем их через npm install --save %имя_модуля%.

В дальнейшем есть шанс получить следующую ошибку от TailWindCSS (при запуске npm run dev)

[vite:css] Nested CSS was detected, but CSS nesting has not been configured correctly.Please enable a CSS nesting plugin *before* Tailwind in your configuration.

Она вызывается из-за того, что мы используем кастомный css для ckeditor

Чтобы этого не происходило, нам необходимо в файле postcss.config.js в корне нашего проекта добавить следующие строки:

'postcss-import': {},
'tailwindcss/nesting': {},

как на скриншоте

Почти все

Нам осталось только в нашем шаблоне между тегов <head> добавить

@Vite(['resources/js/editor.js', 'resources/css/editor.css'])

И теперь любой <div> или <textarea> с указанием id="editor" будет вызван с редактором CKEditor5.

Запускаем проект через npm run dev и радуемся полученному результату!

Результат

А Вы заметили пасхалочку на скриншоте?

Все что вам осталось - это настроить дизайн редактора в css файле.

Ну и как-же без ложки дегтя - почему-то конфигурация "language: ru" не срабатывает и редактор остается английским. Возможно не хватает какого-то модуля или же что-то необходимо донастроить. Пока еще не разобрался, но в целом на данном этапе разработки это не сильно критично. Если у Вас есть идеи - welcome!

Update: С языком разобрался. Действительно его необходимо было имортировать. Для этого в ckeditor.ts необходимо вставить строку после импорта { ClassicEditor }

import '@ckeditor/ckeditor5-build-classic/build/translations/ru';

Update2: Также нашел проблему при вставке видео с внешнего источника, например Youtube. В редакторе оно вставляется, а вот в пост не переносится. Лечится доп конфигом там-же в ckeditor.ts в секцию defaultConfig

mediaEmbed: {
previewsInData: true
}

Надеюсь что данный гайд поможет Вам в проектах.

Если вы хотите немного потрындеть, или быть может знаете Laravel или например умеете верстать, ну или просто у вас есть желание как-нибудь помочь с разработкой проекта, милости прошу в мою потрынделку.

В кратце - да, старый добрый, с блекджеком и шлюпками.

Всем спасибо!