Мы реализовали кастомные хуки для Payload CMS на 20+ проектах: от интернет-магазинов до корпоративных порталов. Типовые валидаторы не справляются с проверкой остатков через внешнее API, генерацией уникальных номеров заказов или отправкой уведомлений в Telegram.
В одном проекте требовалось рассчитать скидку на основе истории покупок — это потребовало сложного beforeChange хука с обращением к отдельной таблице. Без кастомного хука пришлось бы менять ядро CMS, что недопустимо. Результат: скидка рассчитывается за 200 мс вместо 5 секунд вручную.
Кастомные хуки встраиваются в жизненный цикл документа без модификации исходного кода Payload. За 5+ лет мы написали десятки таких решений, и каждое требовало глубокого понимания lifecycle коллекций. В среднем один хук экономит 3–4 часа ручной работы в неделю. Каждый хук строго типизирован на TypeScript и покрыт тестами.
Как кастомные хуки решают задачи бизнес-логики?
Хуки Payload работают на разных этапах: beforeChange, afterChange, beforeRead, afterRead, beforeDelete, afterDelete. Каждый хук получает data, req и context. Мы используем строгую типизацию TypeScript, чтобы избежать ошибок на этапе компиляции.
| Тип хука | Задача | Пример использования |
|---|---|---|
beforeChange |
Трансформация данных | Генерация orderNumber, установка createdBy |
afterChange |
Side-эффекты | Отправка email, синхронизация с CRM, инвалидация кэша |
beforeRead |
Безопасность | Фильтрация данных по роли пользователя |
afterRead |
Обогащение | Вычисление subtotal из items, подстановка связанных данных |
beforeDelete |
Защита | Запрет удаления клиента с активными заказами |
Какие типовые ошибки встречаются при разработке хуков?
Необработанная ошибка в 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 } Кейс: интернет-магазин электроники
Требовалась генерация номера заказа вида ELEC-XXXXX (без года, чтобы не устаревать), проверка остатков через внешний API и отправка данных в 1С. Мы реализовали три хука:
- beforeChange — генерация номера и вызов API склада. Если остатков нет — возвращаем ошибку.
- afterChange — отправка email клиенту и создание сделки в CRM.
- afterChange — запись в очередь для синхронизации с 1С (через Bull).
Все хуки типизированы, используют CollectionConfig. Ошибки логируются в Sentry. Результат: заказы обрабатываются без задержек, ручной труд исключён, а синхронизация с 1С происходит раз в минуту. Кастомные хуки в 3 раза быстрее решают задачу валидации по сравнению со встроенными методами Payload.
Как внедрить кастомные хуки: пошаговая инструкция
- Анализ требований: опишите бизнес-логику, определите нужные этапы (beforeChange, afterChange и т.д.).
- Проектирование: спроектируйте схему данных и взаимодействие с внешними сервисами.
- Разработка: напишите код хука с типизацией и обработкой ошибок.
- Тестирование: покройте критичные сценарии unit-тестами.
- Деплой: внедрите через CI/CD с автоматической проверкой.
Процесс работы
| Этап | Длительность | Результат |
|---|---|---|
| Анализ | 1 день | Спецификация хуков с учётом бизнес-логики |
| Разработка | 2–3 дня | Код хуков с unit-тестами |
| Тестирование | 1 день | Проверка в staging-окружении |
| Деплой и документация | 0.5 дня | Merge в main, описание каждого хука |
Что входит в deliverables
- Исходный код хуков с комментариями (TypeScript).
- Тесты на критичные сценарии (покрытие 80%+).
- Документация: описание каждого хука, его назначение, входные/выходные данные.
- Доступ к репозиторию с историей коммитов.
- Поддержка в течение 2 недель после деплоя.
Сроки и как заказать
Срок разработки хуков для одной коллекции — от 1 до 3 дней. Стоимость рассчитывается индивидуально после анализа требований. Если вам нужно внедрить кастомные хуки в Payload CMS — свяжитесь с нами для оценки проекта. Опишите задачу, и мы предложим оптимальное решение. Подробнее о хуках читайте в официальной документации Payload. Закажите разработку кастомных хуков под вашу задачу — гарантируем прозрачность и качество.