Розробка кастомних хуків (Hooks) Payload CMS

Ми реалізували кастомні хуки для Payload CMS на 20+ проектах: від інтернет-магазинів до корпоративних порталів. Типові валідатори не справляються з перевіркою залишків через зовнішнє API, генерацією унікальних номерів замовлень або відправкою сповіщень у Telegram.

В одному проекті потрібно було розрахувати знижку на основі історії покупок — це вимагало складного beforeChange хука зі зверненням до окремої таблиці. Без кастомного хука довелося б змінювати ядро CMS, що неприпустимо. Результат: знижка розраховується за 200 мс замість 5 секунд вручну.

Кастомні хуки вбудовуються в життєвий цикл документа без модифікації вихідного коду Payload. За 5+ років ми написали десятки таких рішень, і кожне вимагало глибокого розуміння lifecycle колекцій. В середньому один хук економить 3–4 години ручної роботи на тиждень, що на 80% скорочує час на валідацію. Кожен хук строго типізований на TypeScript і покритий тестами.

Як кастомні хуки вирішують завдання бізнес-логіки?

Хуки Payload працюють на різних етапах: beforeChange, afterChange, beforeRead, afterRead, beforeDelete, afterDelete. Кожен хук отримує data, req і context. Ми використовуємо строгу типізацію TypeScript, щоб уникнути помилок на етапі компіляції.

Які типові помилки трапляються при розробці хуків?

Необроблена помилка в beforeChange блокує збереження, а в afterChange може призвести до втрати даних. Ми завжди використовуємо патерн: у валідаційних хуках — throw new Error, у побічних — логування + повторна спроба. Для тривалих операцій ставимо завдання в чергу через Bull або Redis. Хук beforeRead дозволяє приховати чутливі поля для непідготовлених користувачів. Наприклад, менеджер бачить тільки свої замовлення, а адмін — всі. Це реалізується фільтрацією по req.user. Після операції afterDelete можна записати лог в окрему колекцію для аудиту.

Приклад коректної перевірки залишків:

const validateStock: CollectionBeforeChangeHook = async ({ data, req }) => { for (const item of data.items) { const { stock } = await externalApi.checkStock(item.product) if (stock < item.quantity) { throw new Error(`Недостатньо товару "${item.name}" на складі`) } } return data }