Інтеграція Directus з React ламається на кеші та правах доступу
Інтеграція Directus з React майже ніколи не ламається на етапі «отримали дані та відрендерили». Перша відмова приходить пізніше: контент-редактор править матеріал в адмінці, а фронтенд ще добу віддає стару версію з кешу.
Причина — дані тягнуть напряму з браузера та кешують на рівні CDN або збирача, не прив'язуючи інвалідацію до події зміни запису. У підсумку розсинхрон між адмінкою та сайтом живе до наступного релізу, а не до наступної правки.
Друга типова поломка — права доступу. Коли запити до Directus йдуть з клієнтського коду, у збірку потрапляє статичний токен із широкими правами: він видимий у вихідниках сторінки та відкриває доступ до колекцій, які користувачу бачити не належить.
Публічна роль у Directus має віддавати лише дозволені поля та записи, а все, що потребує авторизації, йде через серверний шар застосунку, де токен не залишає інфраструктуру.
Третя проблема — дублі запитів. Компоненти React під час гідратації та повторного монтування смикають один і той самий ендпоінт по кілька разів, а прямі виклики з браузера не проходять через спільний шар кешування.
За активного трафіку це перетворюється на зайве навантаження на Directus і на різний стан у компонентів, які чекають на одні й ті самі дані.
Усі три відмови лежать в одній площині: межа між клієнтом і сервером проведена не там, де потрібно. Розбираємо, як це закривається на рівні архітектури, а не точковими латками.
Що дає зв'язка Directus і Next.js на практиці
Швидкість збірки та час до першого контенту
Directus віддає контент через API, а Next.js забирає його на етапі збірки: сторінки каталогу, статей і лендингів збираються у статику й роздаються з межі мережі.
На практиці це дає час до першого контенту в межах десятих часток секунди замість секунд під час запиту до бази на кожен показ.
Інкрементальна регенерація змінює картину: під час правки матеріалу перезбирається лише зачеплена сторінка, а не весь сайт, тому публікація займає секунди, а не хвилини.
Клас відмов, який зникає
Коли фронтенд звертається до бази напряму, падіння сховища або важкий запит валять весь сайт. Із розділенням шарів відмова обмежена: готова статика продовжує роздаватися з кешу, а збій стосується лише оновлення контенту.
Це переводить аварію з «сайт лежить» у «правки зачекають» — принципово інший клас інцидентів і інший обсяг робіт для чергової зміни.
Продуктивність під навантаженням
Статичні сторінки не навантажують застосунок під час пікових заходів: зростання трафіку впирається в роздачу файлів, а не в запити до бази.
Модель даних і права доступу описуються в Directus один раз, а фронтенд отримує вже готові структури — менше коду на розбір відповідей і менше розбіжностей між адмінкою та сайтом.
Оновлення контенту не потребує викочування нової версії застосунку, тому маркетинг і редакція працюють незалежно від релізного циклу розробки.
Режими роботи: статика, інкрементальне перезбирання, живий потік
Directus віддає контент через API, але спосіб доставки цього контенту на фронт визначає, як швидко правка в редакції стає видимою відвідувачу і скільки навантаження лягає на сервер.
На практиці обирають між трьома режимами — і часто комбінують їх на одній сторінці: каталог збирається статично, картка товару оновлюється інкрементально, а блок наявності підтягується живим потоком.
| Режим | Коли підходить | Обмеження |
|---|---|---|
| Статика | Лендінги, документація, сторінки з рідкісними правками | Повне перезбирання при кожній зміні; контент застаріває між збираннями |
| Інкрементальне перезбирання | Каталоги, блоги, сторінки з частим, але не миттєвим оновленням | Потрібні вебхуки з Directus; затримка між правкою і публікацією; складніше налагоджувати кеш |
| Живий потік | Лічильники, статуси, чати, залишки на складі | Потребує постійного з'єднання; не індексується пошуковиками; дорожче за навантаженням |
Статика дає мінімальний час відгуку і передбачуване навантаження, але кожна правка означає перезбирання всього сайту. Інкрементальне перезбирання знімає це обмеження: вебхук з Directus за подією публікації перезбирає лише зачеплені сторінки, а решта залишаються в кеші.
Живий потік закриває сценарії, де дані змінюються між перезбираннями, — але його не можна робити основою для сторінок, які мають потрапляти в пошук.
Вибір режиму — це компроміс між свіжістю контенту, навантаженням і складністю підтримки. Помилка на цьому етапі проявляється пізніше: або редактор чекає публікації годинами, або сервер не витримує перезбирань при кожному збереженні. Розбираємо, як підібрати режим під конкретний розділ сайту.
Як ми впроваджуємо інтеграцію: від аудиту до передачі
Впровадження починається з аудиту, а не з коду. На цьому етапі ми розбираємо поточний стек, дивимося, де живуть дані та як вони потрапляють на фронтенд, які розділи оновлюються частіше за інших і хто з команди замовника буде працювати з контентом.
Аудит дає карту вузьких місць: дублювання даних між сервісами, ручне вивантаження, сторінки, які перезбираються повністю через одну правку. Без цієї карти будь-яка інтеграція перетворюється на переписування навмання.
Далі проєктуємо схему даних — колекції, зв'язки, права доступу за ролями, поля з валідацією. Схема фіксується до налаштування, тому що змінювати її після підключення фронтенду дорожче в рази.
- Аудит. Інвентаризація джерел даних, точок інтеграції та сценаріїв редактора. На виході — перелік вузьких місць із пріоритетами.
- Схема даних. Модель колекцій, типи зв'язків, ролі та політики доступу, правила валідації на стороні API.
- Налаштування. Підключення шару даних до застосунку, режими віддачі контенту, кешування та інвалідація за подіями зміни.
- Перевірка. Тести на вибірку, права, поведінку при недоступності джерела; прогін сценаріїв редактора від чернетки до публікації.
- Передача. Доступи, середовища, інструкції для контент-команди та розробників, розбір типових операцій.
- Супровід. Моніторинг помилок інтеграції, оновлення схеми під нові розділи, реакція на зміни навантаження.
Кожен крок закінчується артефактом, який можна перевірити: карта інтеграцій, опис схеми, конфігурація середовищ, звіт за тестами. Це знімає головний ризик — коли після запуску ніхто не розуміє, чому сторінка показує застарілі дані.
Передача включає не лише документацію, а й спільний розбір: ваша команда повинна вміти додати поле або розділ без нас.
Опишіть задачу — повернемося з оцінкою та планом за цими етапами.
Артефакти на виході: конфігурації, схеми, регламенти
Інтеграція Directus з фронтендом — це не «налаштували й забули»: конфігурація колекцій, ролі, права на поля та вебхуки живуть у репозиторії та змінюються разом із продуктом.
Тому на виході ви отримуєте не набір розрізнених налаштувань в адмінці, а відтворюваний комплект, за яким інтеграцію можна розгорнути заново, передати іншій команді або розширити без археології.
- Конфігурація схеми Directus — колекції, поля, зв'язки та типи у вигляді декларативних файлів у репозиторії: схема піднімається на чистому середовищі однією командою, а не збирається руками.
- Схеми даних і зв'язків — діаграма колекцій, напрямків зв'язків і каскадів видалення: видно, що станеться із записом при видаленні батька, до того як це трапиться в проді.
- Політики доступу — ролі, права на колекції та окремі поля, правила фільтрації на рівні рядків: редактор бачить лише свої матеріали, публічний API віддає лише опубліковане.
- Конфігурація збірки та кешу — правила інкрементальної регенерації сторінок і те, які зміни контенту її запускають: правка в Directus оновлює потрібні сторінки, а не весь сайт.
- Налаштування вебхуків і real-time — які події публікації смикають фронтенд, із якою затримкою контент доходить до відвідувача і як обробляється недоставлена подія.
- Регламент роботи з контентом — які поля обов'язкові, що перевіряється перед публікацією, як заводиться нова сутність: редактор не ламає верстку, бо правила зашиті в схему.
- Документація інтеграції — карта ендпоінтів, змінні середовища, порядок розгортання та відкат на попередню версію схеми.
- Інструкція з експлуатації — що робити при розсинхроні кешу, як додати поле без простою і куди дивитися при помилці доступу.
Кожен артефакт версіонується разом із кодом: зміна прав або схеми проходить рев'ю та відкочується так само, як звичайний реліз. Опишіть вашу задачу — повернемося з оцінкою та планом, які з цих документів і конфігурацій потрібні саме вам.
Кейс: як ми прибрали розсинхрон контенту та прискорили збірку
Що було до змін
Проєкт — медійний портал з каталогом і редакційним розділом: контент-менеджери правили матеріали в адмінці, фронтенд збирався за розкладом.
Правки не потрапляли на прод до наступного циклу — у середньому 40 хвилин очікування, а за термінових публікацій редакція дублювала матеріал вручну.
Розсинхрон між тим, що бачив редактор в інтерфейсі, і тим, що віддавав сайт, сягав 15% правок за тиждень: частина змін губилася під час перезапису, частина виїжджала в прод у неповному вигляді.
Збірка займала 11 хвилин і перезбирала весь сайт цілком через одну правку в картці товару. Відкати траплялися 2-3 рази на тиждень: контент-команда не могла передбачити, що саме потрапить у реліз, і просила повернути попередній стан.
Що змінили
Ми перевели фронтенд на інкрементальну перезбірку: правка в колекції позначається тегом, і перезбираються лише сторінки, які її використовують. Повна збірка залишилася для змін у шаблонах і навігації.
Паралельно налаштували потік оновлень від адмінки до фронтенду — редактор бачить результат одразу після збереження, без очікування циклу.
Додали правило відкату: кожен реліз прив'язаний до знімка контенту, повернутися до попереднього стану можна однією операцією. Логи збірки та публікацій зведені в одну панель — видно, яка правка спричинила перезбірку і скільки вона зайняла.
Що стало
| Метрика | До | Після |
|---|---|---|
| Час збірки після правки | 11 хв | 40-60 сек |
| Частка розсинхрону правок | до 15% | менше 1% |
| Відкати на тиждень | 2-3 | поодинокі, за плановими релізами |
| Затримка публікації | до 40 хв | секунди |
Збірка прискорилася завдяки відмові від повного перезбору: тепер перезбирається лише задіяна ділянка. Розсинхрон зник, бо джерело правди одне — адмінка, а фронтенд отримує зміни потоком, а не пакетом за розкладом.
Відмови перестали бути аварійними: знімок контенту дозволяє повернутися до робочого стану без ручного звіряння.
Стек тут вторинний — важлива схема: єдине джерело контенту, точкова перезбірка та передбачуваний відкат. Такий підхід переноситься на каталоги, лендінги та особисті кабінети, де контент змінюється частіше, ніж код.
Чим відрізняється інкрементальне перезбирання від живого потоку?
Інкрементальне перезбирання та живий потік вирішують одне завдання — доставити свіжий контент у готову сторінку — але по-різному влаштовані й по-різному ламаються.
Інкрементальне перезбирання працює на стороні сервера: при зміні матеріалу позначається лише та сторінка, яка від нього залежить, і вона перебудовується у фоні, поки відвідувачі отримують попередню версію з кешу.
Живий потік тримає з'єднання між браузером і джерелом даних відкритим і підміняє блок прямо в інтерфейсі, без перезавантаження і без участі серверного кешу.
Звідси головна відмінність — у моменті оновлення. Інкрементальне перезбирання дає затримку від кількох секунд до хвилини: контент змінюється рідко, зате сторінка віддається статикою і тримає навантаження.
Живий потік оновлює дані миттєво, але кожне відкрите з'єднання — це ресурс, який треба супроводжувати, а при обриві зв'язку інтерфейс має коректно показати застарілі дані, а не порожнечу.
Вибір режиму визначається природою контенту, а не зручністю розробника. Каталог, блог, лендінг, документація — це інкрементальне перезбирання: матеріал змінюється за розкладом, важлива швидкість віддачі та стійкість до піків.
Панелі моніторингу, чати, статуси замовлень, спільне редагування — живий потік: тут застаріле значення на екрані дорожче, ніж вартість з'єднання.
На практиці режими майже завжди співіснують на одному сайті. Статична частина збирається інкрементально, а окремі блоки підписуються на живий потік через клієнтський компонент — так сторінка залишається швидкою, а критичні дані не відстають.
Ми розводимо ці зони на етапі проєктування схеми даних, щоб не перебудовувати всю сторінку заради одного лічильника і не тягнути живе з'єднання туди, де вистачить перезбирання.
Часті технічні сумніви при інтеграції Directus
Перед стартом проєкту майже завжди виринають одні й ті самі питання: чи не стане зовнішня система точкою відмови, чи витримає вона пікове навантаження, чи реально піти з неї без переписування фронтенду. Нижче — розбір кожного, з інженерного боку.
Безпека: чи не отримає зовнішній сервіс доступ до наших даних?
Доступ розмежовується на рівні ролей і колекцій: публічній ролі видаються лише ті поля, які реально потрібні фронтенду, решта закрита. Токени для серверних запитів живуть у змінних середовища й не потрапляють у клієнтський бандл — браузер їх не бачить. Пишемо на дані правила доступу, а не «довіряємо всьому, що прийшло з фронту».
Навантаження: чи витримає система піки та зростання контенту?
Статику й сторінки, що рідко змінюються, віддаємо з кешу, до джерела йдемо лише за свіжими даними — при зростанні трафіку це знімає основну частину запитів. Важкі вибірки закриваємо індексами та обмеженням полів у відповіді.
Якщо контенту стане в рази більше, вузьке місце видно заздалегідь за метриками, а не за скаргами користувачів.
Міграція: що буде з поточним сайтом і даними?
Переносимо дані пакетно, з перевіркою цілісності на кожному кроці, і тримаємо стару систему робочою до підтвердженого перемикання. Схему описуємо декларативно — її можна підняти в новому середовищі однією командою. Відкат можливий на будь-якому етапі, поки не відключили попередній контур.
Підтримка: чи не залишимося ми самі з чужою системою?
Віддаємо конфігурації, схему даних, опис ролей і доступів, інструкції щодо типових операцій. Наші інженери залишаються на зв'язку із супроводу: оновлення, розбір інцидентів, доопрацювання моделей контенту. Система залишається керованою, навіть якщо завдання веде інша команда.
Опишіть ваше завдання — повернемося з оцінкою та планом щодо інтеграції.
Обговоримо ваше завдання і повернемося з оцінкою
Щоб оцінка була предметною, а не «середньою по ринку», нам потрібен контекст щодо завдання: як влаштована поточна система, які дані вона зберігає і які сценарії критичні. Нижче — що уточнюємо на першій розмові та які матеріали допомагають порахувати обсяг робіт точно.
- Мета і межі. Що має змінитися: новий розділ, інтеграція Directus з фронтендом, прискорення видачі або перехід на іншу схему даних. Фіксуємо, що входить у перший етап, а що свідомо відкладаємо.
- Поточний стек і стан. Які фреймворки та версії в проді, де хостяться сервіси, як влаштовані збірка і викладка. Якщо проєкт уже живе — потрібен доступ до репозиторію або стислий опис архітектури.
- Модель даних і контент. Які сутності та зв'язки є зараз, хто і як їх редагує, які поля обов'язкові. Це визначає схему колекцій у Directus і обсяг міграції.
- Сценарії та навантаження. Які сторінки кешуються, де потрібен real-time, скільки користувачів і запитів очікується в піку. Від цього залежить вибір між статичною генерацією та оновленням за запитом.
- Обмеження та доступи. Вимоги до ролей і прав, робота із зовнішніми сервісами, правила зберігання персональних даних, середовища для тестів і приймання.
- Терміни та пріоритети. Що потрібно до конкретної дати і що можна випускати частинами. Так ми запропонуємо план, який не блокує інші напрями.
У відповідь ви отримаєте оцінку за етапами з трудозатратами, чернетку плану робіт із порядком випуску та список ризиків, які варто закрити до старту. Якщо даних поки мало — опишіть завдання словами, решту уточнимо в листуванні або на дзвінку.
