Розробка кастомних розширень Directus під ключ

Розробка кастомних розширень Directus під ключ

При впровадженні Directus в корпоративну інфраструктуру часто виникає необхідність інтеграції з обліковими системами: 1С, CRM, складськими базами. Стандартні REST та GraphQL API не завжди покривають специфіку бізнес-логіки — потрібні нестандартні обробники подій, кастомні ендпоінти або складна валідація. Саме тут допомагають кастомні розширення Directus: вони дозволяють розширити функціонал без модифікації ядра. Типовий приклад: при створенні замовлення потрібно відправити дані в CRM, згенерувати PDF-рахунок і внести запис у лог. Hook-розширення впорається з цим за кілька рядків TypeScript, а Operation в Flows запустить ланцюжок дій.

Ми розробляємо кастомні розширення Directus вже багато років і реалізували понад 30 рішень для синхронізації з 1С, генерації PDF-звітів, інтеграції з Telegram-ботами. Всі розширення пишуться на TypeScript з використанням офіційного SDK.

Кастомні розширення Directus: типи та приклади коду

Типи розширень

Порівняння кастомних розширень і готових плагінів

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

Hook-розширення підписуються на події action (після зміни) або filter (до збереження). У типовому кейсі — при створенні замовлення відправляємо дані в CRM. Код обробника виглядає так:

// extensions/hooks/lifecycle-events/index.ts
import type { HookExtensionContext } from '@directus/types'

export default ({ action, filter, schedule, init }: HookExtensionContext) => {
  action('items.create', async ({ collection, item, accountability }) => {
    if (collection === 'orders') {
      await fetch(process.env.CRM_WEBHOOK!, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          event: 'order_created',
          orderId: item.id,
          total: item.total,
        }),
      })
    }
  })
}

Цей код можна доповнити обробкою помилок та повторною відправкою при збоях — ми включаємо такі сценарії в розробку.

Що таке Endpoint-розширення та як його створити?

Endpoint-розширення дозволяють додати свої маршрути Express. Наприклад, для побудови звіту по продажах з фільтрацією за датами:

// extensions/endpoints/reports/index.ts
import type { EndpointExtensionContext } from '@directus/types'
import { Router } from 'express'

export default (router: Router, { services, getSchema }: EndpointExtensionContext) => {
  router.get('/sales', async (req, res) => {
    const schema = await getSchema()
    const { ItemsService } = services
    const ordersService = new ItemsService('orders', { schema, accountability: req.accountability })
    const orders = await ordersService.readByQuery({
      filter: { status: { _eq: 'completed' } },
      fields: ['id', 'total', 'date_created']
    })
    const totalRevenue = orders.reduce((sum, o) => sum + (o.total || 0), 0)
    res.json({ totalOrders: orders.length, totalRevenue })
  })
}

Ми часто додаємо пагінацію, сортування та кешування. Наші ендпоінти проходять навантажувальне тестування.

Як Operation-розширення автоматизують бізнес-процеси?

Operation-розширення використовуються в Flows. Вони складаються з двох файлів: серверна логіка та UI для побудовника Flows.

// extensions/operations/send-sms/index.ts (сервер)
export default {
  id: 'send-sms',
  handler: async ({ phone, message }, context) => {
    const response = await fetch('https://api.sms-provider.com/send', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.SMS_API_KEY}`
      },
      body: JSON.stringify({ to: phone, text: message })
    })
    if (!response.ok) throw new Error('SMS failed')
    return { sent: true }
  }
}

// extensions/operations/send-sms/app.ts (UI)
export default {
  id: 'send-sms',
  name: 'Send SMS',
  icon: 'sms',
  description: 'Відправити SMS через провайдера',
  options: [
    {
      field: 'phone',
      type: 'string',
      meta: {
        interface: 'input',
        required: true
      }
    },
    {
      field: 'message',
      type: 'text',
      meta: {
        interface: 'input-multiline',
        required: true
      }
    }
  ]
}

Чому кастомні розширення кращі за готові плагіни?

Готові плагіни часто не відповідають специфіці бізнесу: вони або надлишкові, або не вистачає функції. Кастомне розширення пишеться точно під задачу. Наприклад, Hook може не тільки відправити дані в CRM, але й перевірити дублікати, а Endpoint — згенерувати складний звіт з фільтрацією. Ви отримуєте саме те, що потрібно, без зайвого коду.

Наші проекти показують, що кастомне рішення скорочує час на інтеграцію в середньому на 40% порівняно з доопрацюванням готових плагінів. При цьому ймовірність збоїв при оновленні знижується на 60%. Для типових сценаріїв у нас є готові шаблони — зв'яжіться з нами, щоб отримати їх.

Етапи розробки розширення під ключ

1. Аналіз вимог (1 день) — інтерв'ю з замовником, виявлення точок інтеграції та форматів даних.
2. Прототип (1 день) — створення заготовки Hook та тестового ендпоінту, узгодження API.
3. Розробка (1–3 дні) — написання коду, модульні тести, інтеграція із зовнішніми сервісами.
4. Staging (1 день) — розгортання в тестовому середовищі, перевірка з реальними даними.
5. Документація (0.5 дня) — детальний README, інструкція з встановлення та конфігурації.

extensions/
  ├── hooks/sync-to-crm/
  │   ├── index.ts
  │   └── package.json
  ├── endpoints/reports/
  │   ├── index.ts
  │   └── package.json

Що входить до розробки кастомних розширень

• Вихідний код у вашому репозиторії (TypeScript, з коментарями).
• Документація з встановлення, налаштування та використання.
• Тестування в staging-середовищі.
• Гарантія виправлення помилок протягом місяця.
• Консультації з інтеграції та подальшої підтримки.

Терміни та орієнтовна вартість

Розробка одного розширення (Hook або Endpoint) займає від 2 до 4 днів. Комплексний набір із трьох розширень (Hook + Endpoint + Operation) — 3–5 днів. Вартість розраховується індивідуально залежно від складності. Зв'яжіться з нами для точної оцінки.

Замовте розробку кастомного розширення — отримайте готове рішення з документацією та гарантією.