1~
2Бiльшостi виробничих застосункiв потрiбна робота, яка не вписується в цикл запит/вiдповiдь: вiдправлення листiв, обробка завантажень, запуск AI-пайплайнiв, синхронiзацiя сторонiх даних, генерацiя звiтiв. Традицiйна вiдповiдь - черга (Redis, SQS, RabbitMQ), флот воркерiв, планувальник та крихка купа склеювального коду, який ламається при кожному деплої.
3~
4[Trigger.dev](https://trigger.dev) згортає цей стек у єдиний TypeScript SDK. Ви пишете функцii, викликаєте ix звiдки завгодно, а платформа займається чергами, повторами, спостережнiстю, плануванням i довговiчним виконанням. Tasks працюють стiльки, скiльки потрiбно - жодних 10-секундних serverless-таймаутiв, жодноi втраченоi роботи при редеплоi.
5~
6## Чому Trigger.dev
7~
8Зрушення 2026 року - довговiчне виконання. Воркфлоу повиннi виживати пiсля перезапускiв, крашiв, деплоiв i rate limits. Вони також повиннi стрiмити прогрес у UI у режимi реального часу та зупинятися для введення людини. Trigger.dev був перебудований навколо цих вимог у версii 3 i продовжує розширювати свою AI-iнфраструктурну поверхню.
9~
10```mermaid
11graph LR
12    App[Ваш додаток] -->|trigger| API[API Trigger.dev]
13    API --> Queue[Довговiчна Queue]
14    Queue --> Worker[Worker контейнер]
15    Worker -->|run task| Task[Код вашого Task]
16    Task -->|metadata| Realtime[Реалтайм-стрiм]
17    Realtime --> UI[React UI]
18    Worker --> Storage[Сховище стану Run]
19```
20~
21Модель проста: ви визначаєте tasks як експорти, SDK iх пiдхоплює, платформа планує та запускає iх в iзольованих контейнерах, а стан run зберiгається, щоб ви могли вiдновити, повторити та спостерiгати.
22~
23## Початок роботи
24~
25### Iнiцiалiзацiя проекту
26~
27```bash
28npx trigger.dev@latest login
29npx trigger.dev@latest init
30```
31~
32Це створює файл `trigger.config.ts` i каталог `trigger/` з прикладами tasks. Файл config - джерело iстини для вашого проекту: якi каталоги мiстять tasks, налаштування зборки, lifecycle hooks та опцii рантайму.
33~
34```typescript
35// trigger.config.ts
36import { defineConfig } from "@trigger.dev/sdk";
37~
38export default defineConfig({
39  project: "proj_abc123",
40  runtime: "node",
41  logLevel: "log",
42  maxDuration: 3600,
43  retries: {
44    enabledInDev: true,
45    default: {
46      maxAttempts: 3,
47      factor: 2,
48      minTimeoutInMs: 1000,
49      maxTimeoutInMs: 30_000,
50    },
51  },
52  dirs: ["./trigger"],
53});
54```
55~
56### Запуск tasks локально
57~
58```bash
59npx trigger.dev@latest dev
60```
61~
62Dev-сервер пiдключається до хмари, реєструє вашi tasks та стрiмить runs через ваш локальний код. Ви ставите breakpoints у редакторi та потрапляєте у них на справжнiх тригерах - той самий цикл, який ви б використовували в будь-якому звичайному Node.js-проектi.
63~
64## Визначення Task
65~
66Task - це об'єкт, який експортується з унiкальним `id` та функцiєю `run`. SDK iнспектує експорти у `dirs` та реєструє iх автоматично.
67~
68```typescript
69// trigger/send-welcome-email.ts
70import { task } from "@trigger.dev/sdk";
71import { Resend } from "resend";
72~
73const resend = new Resend(process.env.RESEND_API_KEY);
74~
75export const sendWelcomeEmail = task({
76  id: "send-welcome-email",
77  retry: {
78    maxAttempts: 5,
79    factor: 1.8,
80    minTimeoutInMs: 500,
81    maxTimeoutInMs: 30_000,
82  },
83  run: async (payload: { email: string; name: string }) => {
84    const { data, error } = await resend.emails.send({
85      from: "hello@spinny.dev",
86      to: payload.email,
87      subject: `Welcome, ${payload.name}`,
88      html: `<p>Glad you are here, ${payload.name}.</p>`,
89    });
90~
91    if (error) throw error;
92    return { messageId: data?.id };
93  },
94});
95```
96~
97Три речi, на якi варто звернути увагу:
98~
991. **У тiлi run немає таймауту.** Платформа керує часом виконання через `maxDuration` у config, а не у рантаймi.
1002. **Throws - це повтори.** SDK ловить виключення та перезапускає з експоненцiйним backoff згiдно з полiтикою `retry`.
1013. **Значення, що повертається, зберiгається.** Iншi tasks та ваш фронтенд можуть читати `run.output` звiдки завгодно.
102~
103## Тригер Tasks
104~
105Ви викликаєте task з бекенду, API-роутiв або iншого task.
106~
107```typescript
108import { sendWelcomeEmail } from "@/trigger/send-welcome-email";
109~
110const handle = await sendWelcomeEmail.trigger(
111  { email: "user@example.com", name: "Alex" },
112  {
113    idempotencyKey: `welcome-${userId}`,
114    concurrencyKey: `tenant-${tenantId}`,
115    queue: { name: "emails", concurrencyLimit: 50 },
116    delay: "30s",
117    ttl: "10m",
118  }
119);
120~
121console.log(handle.id); // run_xyz - використовуйте для вiдстеження або вiдображення прогресу
122```
123~
124Опцii розблоковують багато поведiнки в одному виклику:
125~
126- **`idempotencyKey`** - якщо run з тим самим ключем уже iснує, SDK повертає iснуючий handle замiсть дублювання роботи.
127- **`concurrencyKey`** - серiалiзує runs, що подiляють ключ, щоб ви не перевищили per-tenant rate limit.
128- **`queue.concurrencyLimit`** - глобальний cap для черги по всiх ключах.
129- **`delay`** - планує run на майбутнiй час.
130- **`ttl`** - якщо run не запустився до того часу, автоматично закiнчується.
131~
132### Batch trigger
133~
134Для fan-out навантажень `batchTrigger` приймає до 500 елементiв на виклик i створює один run на елемент.
135~
136```typescript
137await sendWelcomeEmail.batchTrigger(
138  newUsers.map((u) => ({
139    payload: { email: u.email, name: u.name },
140    options: { idempotencyKey: `welcome-${u.id}` },
141  }))
142);
143```
144~
145## Заплановнi Tasks
146~
147Cron-задачi стають декларацiями першого класу. Сам розклад - це окремий об'єкт, який можна прикрiпити до task кiлька разiв.
148~
149```typescript
150// trigger/daily-digest.ts
151import { schedules } from "@trigger.dev/sdk";
152~
153export const dailyDigest = schedules.task({
154  id: "daily-digest",
155  cron: "0 9 * * *",
156  run: async (payload) => {
157    console.log("Scheduled at:", payload.timestamp);
158    console.log("Last run:", payload.lastTimestamp);
159    console.log("Timezone:", payload.timezone);
160    console.log("Next 5 runs:", payload.upcoming);
161~
162    await sendDigestForDate(payload.timestamp);
163  },
164});
165```
166~
167Для розкладiв на кожного tenant - скажiмо, один cron на клiєнта - ви створюєте iх динамiчно через management API.
168~
169```typescript
170import { schedules } from "@trigger.dev/sdk";
171~
172await schedules.create({
173  task: "daily-digest",
174  cron: "0 9 * * *",
175  timezone: "America/New_York",
176  externalId: `customer_${customerId}`,
177  deduplicationKey: `digest-${customerId}`,
178});
179```
180~
181`deduplicationKey` робить виклик iдемпотентним: повторний запуск того самого коду пiд час деплою не накопичує дубльованi розклади.
182~
183## Черги, конкурентнiсть та iдемпотентнiсть
184~
185Три примiтиви покривають бiльшiсть потреб у rate-limiting i впорядкуваннi.
186~
187```mermaid
188graph TB
189    Trigger[trigger payload] --> IK{idempotencyKey<br/>бачили?}
190    IK -->|так| Reuse[Повернути iснуючий run]
191    IK -->|нi| CK[бакет concurrencyKey]
192    CK --> Q[Черга з<br/>concurrencyLimit]
193    Q -->|слот доступний| Run[Запустити task]
194    Q -->|слоти зайнятi| Wait[Чекати в черзi]
195```
196~
197Поширений патерн: одна черга на tenant з малою per-key конкурентнiстю, щоб дотримуватися rate limit вендора, плюс ключ iдемпотентностi, щоб зробити повтори безпечними.
198~
199```typescript
200await syncShopifyOrders.trigger(
201  { shopId },
202  {
203    queue: { name: `shopify-${shopId}`, concurrencyLimit: 2 },
204    concurrencyKey: shopId,
205    idempotencyKey: `sync-${shopId}-${Date.now() / 60_000 | 0}`,
206  }
207);
208```
209~
210## Очiкування та довгострокова робота
211~
212Tasks можуть зупинятися, не утримуючи з'єднання чи спалюючи compute. Платформа зберiгає стан i вiдновлює функцiю, коли очiкування завершується.
213~
214```typescript
215import { wait } from "@trigger.dev/sdk";
216~
217export const onboarding = task({
218  id: "onboarding",
219  run: async (payload: { userId: string }) => {
220    await sendWelcomeEmail.triggerAndWait({ userId: payload.userId });
221    await wait.for({ days: 1 });
222    await sendTipsEmail.trigger({ userId: payload.userId });
223    await wait.until({ date: oneWeekFromSignup(payload.userId) });
224    await sendUpgradeOffer.trigger({ userId: payload.userId });
225  },
226});
227```
228~
229`triggerAndWait` - вбивча фiча: вона тригерить дочiрнiй task i призупиняє батькiвський, доки дочiрнiй не завершиться. Ви компонуєте tasks як async-функцii, але оркестрацiя працює довговiчно через днi або тижнi.
230~
231### Human-in-the-loop з `wait.forToken`
232~
233Для approval-флоу та AI-гейтiв `wait.forToken` зупиняється, доки ваш застосунок не викличе callback з результатом.
234~
235```typescript
236import { task, wait } from "@trigger.dev/sdk";
237~
238export const publishPost = task({
239  id: "publish-post",
240  run: async (payload: { draftId: string }) => {
241    const draft = await generateAIContent(payload.draftId);
242~
243    const token = await wait.createToken({ timeout: "7d" });
244    await notifyEditor({ draftId: draft.id, token: token.id });
245~
246    const decision = await wait.forToken<{ approved: boolean; notes?: string }>(
247      token.id
248    );
249~
250    if (decision.approved) {
251      return await publish(draft);
252    }
253    return await applyFeedback(draft, decision.notes);
254  },
255});
256```
257~
258Редактор вiдкриває UI, перевiряє чернетку, натискає Approve, i ваш бекенд завершує токен. Task продовжує з мiсця, де зупинився - навiть якщо пройшли години чи днi.
259~
260## Lifecycle hooks
261~
262Ви можете прикрiпити `init`, `onStart`, `onSuccess` та `onFailure` до task або глобально у `trigger.config.ts`. Використовуйте iх для tracing, error reporting i спiльноi настройки.
263~
264```typescript
265// trigger.config.ts
266export default defineConfig({
267  // ...
268  init: async () => {
269    Sentry.init({ dsn: process.env.SENTRY_DSN });
270  },
271  onFailure: async ({ error, ctx }) => {
272    Sentry.captureException(error, {
273      tags: { taskId: ctx.task.id, runId: ctx.run.id },
274    });
275  },
276});
277```
278~
279`init` запускається один раз на worker-контейнер при завантаженнi, а не на кожен run, тому це правильне мiсце для налаштування клiєнтiв i пулiв.
280~
281## Реалтайм у фронтендi
282~
283Trigger.dev публiкує змiни стану run - status, metadata, output - через streaming API. React-хуки пiдписуються на цей потiк i автоматично перерендерюють.
284~
285```typescript
286// trigger/process-video.ts
287import { task, metadata } from "@trigger.dev/sdk";
288~
289export const processVideo = task({
290  id: "process-video",
291  run: async (payload: { videoId: string }) => {
292    metadata.set("stage", "transcoding");
293    await transcode(payload.videoId);
294~
295    metadata.set("stage", "thumbnails");
296    await generateThumbnails(payload.videoId);
297~
298    metadata.set("stage", "uploading");
299    const url = await uploadToCDN(payload.videoId);
300~
301    return { url };
302  },
303});
304```
305~
306```tsx
307// components/VideoStatus.tsx
308"use client";
309import { useRealtimeRun } from "@trigger.dev/react-hooks";
310import type { processVideo } from "@/trigger/process-video";
311~
312export function VideoStatus({
313  runId,
314  publicAccessToken,
315}: {
316  runId: string;
317  publicAccessToken: string;
318}) {
319  const { run, error } = useRealtimeRun<typeof processVideo>(runId, {
320    accessToken: publicAccessToken,
321  });
322~
323  if (error) return <p>Error: {error.message}</p>;
324  if (!run) return <p>Loading...</p>;
325~
326  return (
327    <div>
328      <p>Status: {run.status}</p>
329      <p>Stage: {String(run.metadata?.stage ?? "queued")}</p>
330      {run.output?.url && <video src={run.output.url} controls />}
331    </div>
332  );
333}
334```
335~
336Ви генеруєте публiчний access token на сторонi сервера, scoped до конкретного run, i вiдправляєте його клiєнту. Хук обробляє auth, перепiдключення та iнкрементальнi оновлення.
337~
338Для trigger-and-subscribe в один крок:
339~
340```tsx
341import { useRealtimeTaskTrigger } from "@trigger.dev/react-hooks";
342~
343const { submit, run, isLoading } = useRealtimeTaskTrigger<typeof processVideo>(
344  "process-video",
345  { accessToken: publicAccessToken }
346);
347~
348<button onClick={() => submit({ videoId })} disabled={isLoading}>
349  Process video
350</button>;
351```
352~
353## AI-агенти та стрiмiнг
354~
355Trigger.dev став популярним runtime для AI-агентiв, бо тi самi примiтиви - довговiчне виконання, повтори, очiкування, реалтайм-метаданi, human-in-the-loop - це саме те, що потрiбно агентам. Ви стрiмите токени вiд провайдера моделi у `metadata`, поки run вiдбувається, фронтенд рендерить iх наживо, i run переживає довгi tool calls без спалювання serverless-таймауту.
356~
357```typescript
358import { task, metadata } from "@trigger.dev/sdk";
359import { streamText } from "ai";
360import { anthropic } from "@ai-sdk/anthropic";
361~
362export const researchAgent = task({
363  id: "research-agent",
364  maxDuration: 1800,
365  run: async (payload: { question: string }) => {
366    const result = streamText({
367      model: anthropic("claude-opus-4-7"),
368      system: "You are a research assistant. Use the web.",
369      prompt: payload.question,
370      tools: { webSearch },
371    });
372~
373    let fullText = "";
374    for await (const chunk of result.textStream) {
375      fullText += chunk;
376      metadata.set("partial", fullText);
377    }
378~
379    return { answer: fullText, usage: await result.usage };
380  },
381});
382```
383~
384Фронтенд використовує `useRealtimeRun` i читає `run.metadata.partial`, щоб рендерити streaming-вiдповiдь, так само, як ви рендерили б chat completion - окрiм того, що цей переживе повне перезавантаження сторiнки.
385~
386## Деплой
387~
388Деплоi компiлюють вашi tasks у версiйований bundle, будують контейнер i атомарно перемикають трафiк. Старi in-flight runs продовжують використовувати попередню версiю.
389~
390```bash
391npx trigger.dev@latest deploy --env prod
392```
393~
394У CI ви зазвичай пiдключаєте це до того ж workflow, який доставляє ваш додаток:
395~
396```yaml
397# .github/workflows/deploy.yml
398- name: Deploy Trigger.dev
399  env:
400    TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
401  run: npx trigger.dev@latest deploy --env prod
402```
403~
404Для preview-середовищ передайте `--env preview --branch ${{ github.head_ref }}` i Trigger.dev створює iзольоване середовище на кожну гiлку, вiдображаючи те, як Vercel обробляє preview deployments.
405~
406## Self-Hosting vs Cloud
407~
408Trigger.dev вiдкритий пiд лiцензiєю Apache 2.0. Ви можете self-host на будь-якiй контейнернiй платформi (Docker Compose, Kubernetes, Fly.io) або використовувати кероване хмару на trigger.dev.
409~
410| Аспект | Cloud | Self-hosted |
411|--------|-------|-------------|
412| **Setup** | Реєстрацiя, запуск `init` | Запуск docker-compose або Helm chart |
413| **Scaling** | Автоматичне | Ваша вiдповiдальнiсть |
414| **Pricing** | За run + за compute | Тiльки витрати на iнфраструктуру |
415| **Compliance** | SOC 2 | Те, що надає ваше середовище |
416| **Iдеально для** | Бiльшостi команд | Сувороi data residency, кастомноi iнфри |
417~
418SDK i CLI iдентичнi мiж режимами - ви змiнюєте прапорець профiлю i вказуєте на свiй власний екземпляр.
419~
420## Best Practices
421~
422### 1. Тримайте payloads маленькими та серiалiзованими
423~
424Передавайте ID i посилання, а не повнi об'єкти. Завантажуйте данi всерединi task. Це тримає чергу маленькою, payloads дешеви для логування i дозволяє змiнювати джерело даних без перетригерiв.
425~
426### 2. Idempotency keys на кожному зовнiшньому виклику
427~
428Поєднуйте `idempotencyKey` на task trigger з idempotency keys на API ваших вендорiв (Stripe, OpenAI тощо). Повтори будуть безпечними end-to-end.
429~
430### 3. Використовуйте `triggerAndWait` для оркестрацii, а не `Promise.all` тригерiв
431~
432Батько, який викликає `triggerAndWait`, довговiчно компонує дочiрнi tasks. Батько, який тригерить i зразу резолвиться, втрачає спостережнiсть ланцюга.
433~
434### 4. Тегуйте runs
435~
436Додайте `tags` до тригерiв (`tags: ["user:123", "feature:onboarding"]`), щоб ви могли фiльтрувати дашборд i management API за бiзнес-вимiрами.
437~
438### 5. Тримайте `init` iдемпотентним
439~
440Вiн запускається на кожному cold start. Уникайте мiграцiй або одноразових побiчних ефектiв там.
441~
442## Висновок
443~
444Trigger.dev прибирає категорii роботи, для яких ранiше потрiбно було будувати job-систему з нуля. Ви пишете async TypeScript, викликаєте його звiдки завгодно, i платформа дає вам довговiчне виконання, планування, черги, повтори, реалтайм-оновлення i патерни human-in-the-loop з коробки.
445~
446Та сама поверхня, яка живить нiчний cron, - це поверхня, яка живить багатоступеневого AI-агента, що стрiмить у фронтенд i зупиняється для перегляду. Ця конвергенцiя робить фреймворк гiдним серйозного погляду у 2026 роцi, незалежно вiд того, керуєте ви SaaS, якому потрiбна надiйна фонова робота, чи поставляєте AI-фiчi, якi переживають serverless-таймаут.
447~
448> **Чек-лист для початку:**
449>
450> - [x] Зареєструйтесь на trigger.dev або запустiть self-hosted Docker-стек
451> - [x] `npx trigger.dev@latest init` у вашому проектi
452> - [x] Визначте свiй перший task з `task({ id, run })`
453> - [x] Тригерте його з вашого API i подивiться run у дашбордi
454> - [x] Додайте `idempotencyKey` i `concurrencyKey` для production-безпеки
455> - [x] Пiдключiть `useRealtimeRun` до status-компонента
456> - [x] Деплойте з `trigger.dev deploy --env prod` з CI
457~