Кастомна інтеграція Quill у CMS: формати, завантаження, Delta
В одному з проєктів на Next.js 14 знадобився rich-text редактор для адмінки CMS, що обробляє до 5000 записів. Стандартний Quill 2.x не підійшов: його тулбар не дозволяв завантажувати зображення на сервер, а форматування таблиць було відсутнє — довелося б зберігати base64-рядки, що збільшують розмір документа на 30–50%. Вбудовані модулі давали лише базові можливості, але для реального продукту потрібні кастомні обробники та підтримка формату Delta. Ми розробили власні модулі, які інтегруються з React і Vue. Розповімо, які складнощі зустрілися і як їх обійшли.
Чому базовий Quill не підходить для CMS?
Типова установка Quill дає базовий функціонал, але в продакшені виникають проблеми:
- Завантаження зображень. За замовчуванням Quill вбудовує картинки як base64, що роздуває JSON на 30–50%. Ми пишемо кастомний обробник, який завантажує файл на сервер і вставляє URL. Це знижує навантаження на базу даних і прискорює завантаження сторінок.
- Кастомні модулі: таблиці, вкладені списки, колір тексту. Quill розширюється через сторонні плагіни, але вони не завжди стабільні. Для одного проєкту довелося написати модуль для вкладених списків, оскільки готовий не підтримував глибину більше 2 рівнів.
- Збереження в Delta vs HTML. Delta зручний для версіонування та спільного редагування, але часто потрібен HTML для виведення. Ми надаємо обидва варіанти, конвертуючи Delta в HTML за допомогою
quill-delta-to-html.
| Проблема | Рішення | Час реалізації | Економія порівняно з комерційним редактором |
|---|---|---|---|
| base64-зображення | кастомний обробник із завантаженням на сервер | 2–4 години | суттєве зниження витрат |
| відсутність таблиць | плагін quill-better-table |
1–2 години | — |
| складна кастомізація | створення власного модуля на основі Quill API | від 1 дня | значна економія на ліцензіях |
Як ми інтегруємо Quill з кастомними модулями?
Наш процес включає:
- Аналіз вимог до редактора: кнопки, формати, завантаження медіа, підтримка мобільних пристроїв.
- Проектування модулів: кастомні обробники, тема (snow/bubble або власна), налаштування тулбара.
- Реалізація: код на React (react-quill-new), Vue або ванільному JS. Приклад кастомного обробника зображень:
const imageHandler = () => {
const input = document.createElement('input');
input.setAttribute('type', 'file');
input.setAttribute('accept', 'image/*');
input.click();
input.onchange = async () => {
const file = input.files[0];
const formData = new FormData();
formData.append('image', file);
const response = await fetch('/api/media/upload', {
method: 'POST',
body: formData
});
const { url } = await response.json();
const quill = quillRef.current.getEditor();
const range = quill.getSelection(true);
quill.insertEmbed(range.index, 'image', url);
};
};
const MODULES = {
toolbar: {
container: [...],
handlers: { image: imageHandler }
}
};
- Тестування на всіх пристроях і браузерах (Chrome, Firefox, Safari, Edge). Перевіряємо коректну роботу SSR, завантаження зображень, конвертацію Delta->HTML.
- Деплой і документація. Передаємо вихідний код, інструкцію з налаштування та підтримку протягом трьох місяців.
Що дає формат Delta?
Delta — це масив операцій (insert, delete, retain), який легко зберігати, передавати та трансформувати. На відміну від HTML, Delta не втрачає семантику форматування: кожен стиль зберігається як атрибут операції. Це дозволяє реалізувати undo/redo з будь-яким кроком, спільне редагування через OT-алгоритми та автоматичне злиття змін. Як зазначено в описі формату Delta, розмір Delta-об'єкта зазвичай на 40% менший за аналогічний HTML при однаковому контенті. Якщо ваш проєкт потребує версіонування, Delta — правильний вибір.
Порівняння з альтернативами
| Критерій | Quill 2.x | TinyMCE 6 | CKEditor 5 |
|---|---|---|---|
| Розмір бандла (min+gzip) | ~40 КБ | ~200 КБ | ~300 КБ |
| Формат даних | Delta (JSON) | HTML | HTML/JSON |
| Кастомізація | Середня (API модулів) | Висока (плагіни) | Висока (UI) |
| Таблиці | Плагін | Вбудовані | Вбудовані |
| Річна ліцензія (грн.) | 0 (відкритий код) | від 100 000 | від 150 000 |
Quill виграє за швидкістю завантаження та простотою. Якщо не потрібні складні вкладені блоки — це найкращий вибір. Якщо ви сумніваєтеся, зв'яжіться з нами для безкоштовної консультації.
Як уникнути типових помилок при інтеграції?
- Забули вимкнути SSR для Quill у Next.js — отримуєте
document is not defined. Використовуйте динамічний імпорт зssr: false. - Використовуєте застарілий
react-quillзамістьreact-quill-new(останній підтримує React 18 і SSR коректно). - Не обернули обробники в
useCallback— нескінченне перемальовування. - Плутаєте Delta і HTML: при вставці HTML через
setContentsвтрачається форматування. Використовуйтеclipboard.dangerouslyPasteHTMLабо конвертацію.
Що входить у роботу з інтеграції?
- Аналіз вимог і вибір стеку (React, Vue, або Next.js)
- Налаштування тулбара, модулів, теми
- Кастомний обробник завантаження зображень
- Експорт у HTML та/або Delta
- Робота з хуками (onChange, onBlur, validation)
- Документація та навчання команди
- Гарантія на код (3 місяці безкоштовної підтримки)
Терміни та вартість
Термін інтеграції Quill з кастомними модулями — від 1 до 3 днів залежно від складності. Вартість розраховується індивідуально після брифу. У середньому така інтеграція виявляється на 30–50% дешевшою за ліцензування комерційних редакторів. Отримайте консультацію інженера безкоштовно — зв'яжіться з нами для оцінки вашого проєкту.