Кастомні модулі Directus: де штатних можливостей не вистачає
Штатна адмінка Directus закриває типовий CRUD: колекції, поля, ролі, права на рівні записів.
Стеля починається там, де з'являється нестандартна логіка в адмінці — узгодження заявки в три пари очей, перерахунок статусу при зміні пов'язаного запису, вивантаження в облікову систему за подією.
Обмеження штатних колекцій проявляються на складних зв'язках: проміжні таблиці з власною логікою, обчислювані поля, які не можна виразити формулою, права, що залежать не від ролі, а від стану самого запису.
Ціна обхідних шляхів вища, ніж здається. Редактор веде стан вручну в окремому полі — рано чи пізно розходиться з реальністю. Аналітик вивантажує дані та зводить у таблиці — операція повторюється щотижня і тримається на людині.
Автоматизація ручних операцій через зовнішні скрипти за розкладом працює, поки не знадобиться реакція на дію користувача всередині адмінки.
Кастомні модулі Directus вирішують це на рівні розширення платформи: свій інтерфейс в адмінці, свої ендпоінти, хуки на події колекцій, власні перевірки прав. Логіка живе поруч із даними і версіонується разом із ними, а не в чужому скрипті. Штатний інтерфейс при цьому залишається — команда не перенавчається.
Далі розбираємо, як це закривається: які точки розширення використовуємо, що залишаємо на штатних механізмах і де проходить межа між налаштуванням і кодом.
Що дає кастомний модуль: ефект у цифрах і режимах роботи
Кастомні модулі Directus дають вимірюваний ефект там, де штатний інтерфейс змушує редактора ходити трьома екранами заради однієї операції. Модуль збирає сценарій в один екран: вибірка пов'язаних записів, масова дія, валідація на вході.
Типова операція на кшталт «перенести добірку в інший розділ із перезбиранням зв'язків» скорочується з 15–20 хвилин ручної роботи до 40–60 секунд — і перестає залежати від того, чи пам'ятає редактор порядок кроків.
Де ефект видно одразу
- Масові операції. Пакетне редагування 200+ записів однією дією замість поштучного редагування — ручні операції скорочуються на порядок.
- Валідація на вході. Перевірки полів і зв'язків на рівні модуля відсікають биті дані до запису в базу, а не після публікації.
- Ролі та права. Інтерфейс під конкретну роль: редактор бачить лише свої поля, адміністратор — службові. Менше помилок доступу.
- Інтеграції. Зовнішнє джерело підтягується в той самий екран, редактор не перемикається між системами.
Порівняння підходів до розширення
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Розширення штатного інтерфейсу | Точкові правки: поле, підказка, порядок блоків | Не тягне складні сценарії та масові дії |
| Окремий модуль | Свій робочий процес, кілька пов'язаних колекцій, ролі | Потребує підтримки коду при оновленнях платформи |
| Зовнішній сервіс | Логіка живе поза CMS, свої черги та розрахунки | Дублювання доступу, складніша синхронізація прав |
Вибір диктує частота операції: якщо сценарій виконується щодня і зачіпає кілька колекцій — окремий модуль окупає підтримку. Якщо правка разова — достатньо розширення штатного інтерфейсу.
Directus тримає розширення як ізольовані пакети, тому модуль оновлюється окремо від ядра і не блокує перехід на актуальну гілку. Опишіть свій сценарій — повернемося з оцінкою та планом, який варіант розширення закриває задачу з мінімальною підтримкою.
Як ми проєктуємо та впроваджуємо модуль: етапи інженерної роботи
Кастомні модулі Directus ми збираємо як окремий розширюваний шар поверх ядра: він не торкається штатних таблиць і оновлюється незалежно від платформи.
Тому процес починається не з коду, а з розбору задачі та проєктування схеми даних — від неї залежать і права, і продуктивність вибірок.
- Розбір задачі та меж модуля. Фіксуємо, які сутності він додає, з якими колекціями ядра пов'язаний, що віддає назовні через API. На виході — узгоджена схема взаємодії, а не «зробіть красиво».
- Проєктування схеми даних. Описуємо колекції, зв'язки, обчислювані поля та індекси. Окремо перевіряємо, де потрібен каскад при видаленні, а де — м'яке видалення, щоб звітність не втрачала історію.
- Налаштування прав доступу. Ролі, політики та правила на рівні полів і рядків: хто бачить, хто змінює, що доступно лише через серверну логіку. Права описуємо декларативно та версіонуємо разом із кодом.
- Реалізація та підключення хуків. Логіка живе в сервісному шарі модуля, а не в розрізнених обробниках — так її можна тестувати та перевикористовувати в інших проєктах.
- Перевірка на копії бази. Проганяємо міграції та сценарії на знімку реальних даних: обсяги, крайні випадки, конфлікти прав. Це ловить проблеми, які не видні на порожній базі.
- Передача та документація. Віддаємо опис схеми, матрицю прав, інструкцію з розгортання та відкату. Команда замовника може розвивати модуль без нас.
Кожен етап закінчується артефактом, який можна перевірити: схема, матриця доступу, звіт про прогін на копії. Так модуль залишається передбачуваним при оновленнях ядра і не перетворюється на необслуговуваний форк.
Чим кастомний модуль відрізняється від набору хуків і зовнішнього сервісу?
Хуки та автоматизації — це реакція на подію всередині системи: запис створено, оновлено, видалено.
Вони дешеві в розробці й не торкаються інтерфейсу, але живуть у тіні: користувач не бачить, що відбувається, не може запустити логіку вручну й не отримує зворотного зв'язку, крім запису в журналі.
Поки сценарій зводиться до «при зміні поля перерахувати пов'язане значення», хуків достатньо, і городити модуль немає сенсу.
Кастомний модуль потрібен там, де з'являється власний робочий екран усередині адмінки: масові операції над вибіркою, покроковий майстер, зведення по проєкту, погодження з ролями.
Ключова ознака — співробітник має щось натиснути й побачити результат, а не чекати, що система сама відреагує на зміну запису.
Розширення адмінки дає свої права доступу, свою навігацію та ізоляцію: логіка модуля не розмазана по десятку хуків, її видно цілком і можна передати іншому інженеру.
Зовнішній сервіс виграє в іншому: коли навантаження не повинно лягати на застосунок, коли потрібні свої черги, важкі обчислення або інтеграція з чужими системами за розкладом.
Але в нього своя ціна — окремий контур розгортання, синхронізація даних і точка відмови, про яку забувають до першого розходження. Зовнішній сервіс проти модуля — це вибір між «логіка поруч із даними» та «логіка поруч із навантаженням».
На практиці межі такі: хуки — для реакцій на події, модуль — для робочих місць усередині адмінки, зовнішній сервіс — для важкої та фонової обробки. Часто всі три співіснують: модуль запускає операцію, хук фіксує зміну, зовнішній сервіс доводить довгу задачу до кінця.
Помилка — намагатися закрити хуками те, що по суті є інтерфейсом: виходить набір невидимих правил, у якому через пів року не розбереться ніхто.
Тому ми починаємо з розбору сценарію, а не з вибору інструменту. Якщо задача впирається в дії співробітника — проєктуємо модуль; якщо в реакцію на дані — обходимося хуками; якщо в обсяг обчислень — виносимо назовні. Опишіть задачу — повернемося з оцінкою та планом, де буде видно, що саме розширюємо і чому.
Кейс: модуль масових операцій замість ручної роботи в адмінці
Замовник — мережа роздрібних точок з каталогом на кілька десятків тисяч карток — прийшов з конкретним болем: контент-менеджери вручну проставляли ознаки й переносили товари між розділами через адмінку.
Одна операція над партією з 400 позицій займала в оператора близько трьох годин, ішла в кілька проходів і стабільно давала 5-8% помилок: частина карток залишалася зі старою ознакою, частина виїжджала не в той розділ. Помилки спливали вже на вітрині — доводилося відкочувати вручну й звіряти вивантаження.
Що зробили
Написали кастомний модуль масових операцій в адмінці: вибірка за фільтром, пакетна обробка порціями, попередній перегляд змін до застосування та журнал по кожній картці.
Оператор бачить, скільки позицій потрапить під правило, і підтверджує однією дією — замість ручного проходу по кожній.
Метрики до і після
| Показник | До | Після |
|---|---|---|
| Час операції на 400 позицій | ~3 години | 4-6 хвилин |
| Частка помилок при перенесенні | 5-8% | <0.5% |
| Відкат партії | вручну, за журналом вивантаження | однією командою з історії |
Ручні проходи зникли, а разом з ними — клас помилок «забув зняти стару ознаку». Журнал дає трасування: видно, хто, коли і що змінював, — це закриває і розбір інцидентів, і питання доступу.
Модуль зібрано на штатному розширенні Directus, тому оновлення ядра не ламають логіку, а права успадковуються з наявних ролей.
Сумісність, міграція та відкат: що уточнюємо до старту
Перед стартом фіксуємо три речі: на якій гілці Directus працює ваш проєкт, як влаштована схема колекцій і хто має доступ до адмінки.
Кастомні модулі Directus розширюють ядро через штатні точки розширення, тому сумісність із поточною версією перевіряємо першою — якщо проєкт на старій гілці, спочатку плануємо оновлення до актуальної LTS, інакше модуль просто не збереться.
Окремо дивимося, які розширення вже стоять: конфлікт двох модулів на одному хуку ламає адмінку цілком, і це дешевше зловити на етапі розбору, ніж у бою.
Міграція даних — друге джерело сюрпризів. Якщо модуль додає поля або зв'язки, готуємо зворотну міграцію: скрипт перенесення, перевірку цілісності на копії бази та точку повернення.
План відкату описуємо до першого рядка коду — який артефакт відкочуємо, що робимо зі схемою, скільки займає повернення до робочого стану.
Що якщо проєкт на нестандартній збірці? Розбираємо конфігурацію, фіксуємо відхилення від типової та закладаємо їх у план робіт — без сюрпризів у процесі.
Що якщо база велика? Переносимо на репліці, звіряємо кількість записів і зв'язки, тільки потім чіпаємо прод.
Чи можна відкотити модуль без зупинки сервісу?
Так, якщо модуль ізольований і не змінює наявні колекції. Розкочуємо через окремий контейнер, перемикаємо трафік, стару версію тримаємо готовою до повернення. Якщо модуль зачіпає схему — узгоджуємо вікно та робимо резервну копію перед зміною.
На руки замовник отримує:
- конфігурацію модуля та схему колекцій з описом зв'язків;
- скрипти міграції та зворотного відкату з інструкцією запуску;
- матрицю доступів і ролей: хто що бачить і змінює;
- документацію зі встановлення, оновлення та діагностики;
- чеклист перевірки після викату та контакти для ескалації.
Опишіть вашу задачу — повернемося з оцінкою та планом робіт.
Терміни впровадження модуля за етапами
Терміни залежать не від обсягу коду, а від кількості невідомих: скільки сутностей зачіпає модуль, чи є зовнішні системи для інтеграції, наскільки строгі вимоги до прав доступу.
Нижче — орієнтовні терміни за етапами для типового модуля кастомні модулі Directus збирають із готових розширень, тому оцінка вкладається у передбачувані рамки.
Розкид за розробкою визначається інтеграціями: модуль усередині адмінки збирається швидше, ніж модуль із синхронізацією даних у зовнішню систему та зворотним записом.
Якщо частина логіки вже покрита штатними можливостями платформи, етап проєктування скорочується, а розробка переходить у доопрацювання інтерфейсу та прав.
Паралельно з розробкою йде підготовка тестового контуру — це знімає день-два з впровадження. На практиці терміни зсуває не код, а узгодження схеми даних: поки не зафіксовані колекції та зв'язки, розробку починати не можна, інакше переробки з'їдають виграш.
Оцінку даємо після розбору задачі — з планом робіт за етапами та припущеннями, від яких термін залежить.
Сумісність з наявною інфраструктурою замовника
Кастомні модулі Directus не вимагають переїзду на нову платформу: вони підключаються до вашого екземпляра як розширення та працюють поверх поточної схеми даних.
Нижче — типові варіанти розгортання, з якими ми стикуємо модулі, та обмеження, які чесніше побачити до старту, ніж на етапі викочування.
Окремо перевіряємо наявний стек: СУБД та її мажорну гілку, спосіб автентифікації (зовнішній провайдер, LDAP, SSO), сховище файлів (локальне, S3-сумісне), зворотний проксі та політику резервного копіювання.
Модуль, який пише в базу напряму в обхід шару доступу, ламає права та аудит — тому всі операції йдуть через штатні інтерфейси платформи.
Directus залишається ядром, а модуль — розширенням: оновлення платформи не перетворюється на переписування логіки. Опишіть ваш варіант розгортання та поточний стек — повернемося з оцінкою сумісності та планом робіт.
