Кастомні хуки Directus для бізнес-логіки

Коли дані в Directus потребують миттєвої реакції — перевірка коректності замовлення, надсилання сповіщення про нову заявку або синхронізація із зовнішньою системою — стандартних засобів CMS часто не вистачає. Розробка кастомних хунків (Hook Extensions) дозволяє вбудувати бізнес-логіку прямо в ядро: ви підписуєтеся на події CRUD, автентифікації або завантаження файлів і виконуєте довільний код. Це знижує затримки на 30–50% порівняно із зовнішніми викликами API, а також спрощує архітектуру — не потрібно піднімати окремий мікросервіс для обробки даних. Наша команда має 5-річний досвід і понад 30 проєктів на Directus, що забезпечує надійне та продуктивне рішення. Зв'яжіться з нами, щоб обговорити вашу задачу — ми підготуємо оцінку за 1 день.

Проблеми, що вирішуються кастомними хуками

Кастомні хуки усувають необхідність у зовнішніх викликах API для обробки змін — вони працюють у тому ж контексті, що й CMS, що скорочує затримку на 30-50% порівняно із зовнішньою логікою. Типові складності:

• Валідація складних даних — перевірка залишків на складі, коректності зв'язків, унікальності полів. Наприклад, при створенні замовлення хук перевіряє, чи доступний товар у потрібній кількості.
• Побічні ефекти — надсилання сповіщень у Slack/Telegram, запис аудит-логів, інвалідація кешу. Хуки обробляють події в 3–5 разів швидше, ніж зовнішні API-виклики.
• Інтеграції — синхронізація з ERP, CRM (наприклад, 1С), платіжними шлюзами.
• Автоматизація — генерація slug, оновлення залишків, формування звітів за розкладом за допомогою cron.

Чому кастомні хуки кращі за зовнішню логіку?

Зовнішні сервіси додають затримки на мережеві виклики та потребують окремого деплою. Хуки виконуються в тому ж процесі Directus, що знижує TTFB і спрощує моніторинг. Наприклад, при обробці замовлення хук перевіряє залишки за 5 мс, тоді як зовнішній API-виклик займає 50–100 мс. Це особливо важливо для high-load проєктів, де кожна мілісекунда на вагу золота.

Як зробити перший хук валідації?

1. Створіть файл extensions/hooks/custom/index.ts.
2. Експортуйте функцію, яка приймає HookExtensionContext.
3. Викличте filter('items.create', async (payload, meta, context) => { ... }).
4. Для скасування операції викиньте помилку через throw new Error('Повідомлення').
5. Перезапустіть Directus — хук підхопиться автоматично.

Приклад валідації: перевірка, що email унікальний у колекції users. Якщо зайнятий — хук викидає помилку, і запис не створюється.

Типи подій

Порівняння action та filter хунків

Повний приклад Hook Extension

// extensions/hooks/business-logic/index.ts import type { HookExtensionContext } from '@directus/types' import type { EventContext } from '@directus/types' export default ({ action, filter, schedule }: HookExtensionContext) => { // ===== АВТОМАТИЧНА ГЕНЕРАЦІЯ SLUG ===== filter('items.create', (payload, meta) => { if (meta.collection === 'articles' && payload.title && !payload.slug) { payload.slug = generateSlug(payload.title as string) } if (meta.collection === 'products' && payload.name && !payload.slug) { payload.slug = generateSlug(payload.name as string) } return payload }) // ===== ВАЛІДАЦІЯ ===== filter('items.create', async (payload, meta, context) => { if (meta.collection !== 'orders') return payload const { database } = context as EventContext & { database: any } // Перевірити наявність товару if (payload.items && Array.isArray(payload.items)) { for (const item of payload.items) { const product = await database('products') .where({ id: item.product_id }) .first() if (!product) { throw new Error(`Product ${item.product_id} not found`) } if (product.stock < item.quantity) { throw new Error(`Insufficient stock for "${product.name}"`) } } } return payload }) // ===== ІНВАЛІДАЦІЯ КЕШУ ===== action('items.update', async ({ collection, keys, payload }) => { const collectionsToRevalidate = ['articles', 'pages', 'products', 'settings'] if (!collectionsToRevalidate.includes(collection)) return try { await fetch(`${process.env.NEXTJS_URL}/api/revalidate`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-revalidate-secret': process.env.REVALIDATE_SECRET!, }, body: JSON.stringify({ collection, keys }), }) } catch (err) { console.error('Failed to revalidate cache:', err) } }) // ===== СПОВІЩЕННЯ ===== action('items.create', async ({ collection, key, payload }, context) => { if (collection !== 'contact_submissions') return // Сповістити команду в Slack await fetch(process.env.SLACK_WEBHOOK!, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text: `📬 Нова заявка від ${payload.name} <${payload.email}>\n${payload.message}`, }), }) }) // ===== АУДИТ ЛОГ ===== action('items.update', async ({ collection, keys, payload, accountability }) => { if (!accountability?.user) return // Логувати зміни в audit_logs колекцію const { getSchema } = context as any const schema = await getSchema() // ... записати в audit_logs }) // ===== СИНХРОНІЗАЦІЯ ЗАЛИШКІВ ===== action('items.update', async ({ collection, keys, payload }, context) => { if (collection !== 'orders') return if (payload.status !== 'paid') return const { database } = context as EventContext & { database: any } const order = await database('orders') .where({ id: keys[0] }) .first() if (order?.items) { const items = JSON.parse(order.items) for (const item of items) { await database('products') .where({ id: item.product_id }) .decrement('stock', item.quantity) } } }) // ===== CRON — щоденний звіт ===== schedule('0 9 * * 1-5', async () => { const response = await fetch(`${process.env.API_URL}/custom/reports/sales`) const stats = await response.json() await fetch(process.env.SLACK_WEBHOOK!, { body: JSON.stringify({ text: `📊 Звіт за вчора: замовлень ${stats.count}, виручка ${stats.revenue.toLocaleString()} ₴`, }), }) }) } function generateSlug(text: string): string { const translitMap: Record<string, string> = { а: 'a', б: 'b', в: 'v', г: 'g', д: 'd', е: 'e', ё: 'yo', ж: 'zh', з: 'z', и: 'i', й: 'y', к: 'k', л: 'l', м: 'm', н: 'n', о: 'o', п: 'p', р: 'r', с: 's', т: 't', у: 'u', ф: 'f', х: 'h', ц: 'ts', ч: 'ch', ш: 'sh', щ: 'sch', ъ: '', ы: 'y', ь: '', э: 'e', ю: 'yu', я: 'ya', } return text .toLowerCase() .replace(/[а-яё]/g, char => translitMap[char] || char) .replace(/\s+/g, '-') .replace(/[^\w-]/g, '') .replace(/-+/g, '-') .slice(0, 100) } 

Як отримати доступ до даних з хунків?

Через context.database (Knex instance) можна виконувати прямі SQL-запити або використовувати ItemsService для роботи з колекціями — це дає гнучкість і контроль. Directus Documentation рекомендує використовувати ItemsService для єдності, але прямий доступ через Knex виправданий при складних join-запитах або масових операціях.

Реальний кейс: інтеграція з 1С

Для великого інтернет-магазину ми реалізували автоматичну синхронізацію замовлень і залишків через хуки. Після оплати замовлення хук надсилає дані в 1С через REST API, а при зміні залишків у зовнішній системі — оновлює Directus. Час синхронізації скоротився з 15 хвилин до 5 секунд. Навантаження на сервер знизилося на 40% за рахунок виключення зайвих API-викликів. Економія на розробці інтеграції склала 50% часу порівняно з традиційним підходом. Замовте розробку кастомних хунків Directus і автоматизуйте бізнес-процеси без зайвих витрат.

Що входить у роботу

• Вихідний код з коментарями на TypeScript
• Документація з установки та налаштування (README)
• Доступ до приватного репозиторію Git
• Навчання команди (1 година онлайн)
• Підтримка протягом 2 тижнів після здачі

Орієнтовні строки

Розробка типового набору з 3–5 хунків (валідація, сповіщення, кеш) займає від 2 до 5 робочих днів залежно від складності інтеграцій. Терміни уточнюються після аналізу вашої бізнес-логіки.

Гарантії та підтримка

Ми — команда з 5-річним досвідом розробки на Directus, яка виконала понад 30 проєктів з кастомізації, включаючи інтеграції з 1С, CRM та платіжними системами. Гарантуємо якість коду, дотримання строків і повну підтримку. Отримайте консультацію інженера — ми відповімо на будь-які питання.