1~
2Most production applications need work that does not fit the request/response cycle: sending emails, processing uploads, running AI pipelines, syncing third-party data, generating reports. The traditional answer is a queue (Redis, SQS, RabbitMQ), a worker fleet, a scheduler, and a fragile pile of glue code that breaks on every deploy.
3~
4[Trigger.dev](https://trigger.dev) collapses that stack into a single TypeScript SDK. You write functions, you call them from anywhere, and the platform handles queuing, retries, observability, scheduling, and durable execution. Tasks run for as long as they need - no 10-second serverless timeout, no lost work on redeploys.
5~
6## Why Trigger.dev
7~
8The shift in 2026 is durable execution. Workflows must survive restarts, crashes, deploys, and rate limits. They must also stream progress back to the UI in real time and pause for human input. Trigger.dev was rebuilt around these requirements with version 3 and continues to expand its AI infrastructure surface.
9~
10```mermaid
11graph LR
12    App[Your App] -->|trigger| API[Trigger.dev API]
13    API --> Queue[Durable Queue]
14    Queue --> Worker[Worker Container]
15    Worker -->|run task| Task[Your Task Code]
16    Task -->|metadata| Realtime[Realtime Stream]
17    Realtime --> UI[React UI]
18    Worker --> Storage[Run State Store]
19```
20~
21The model is simple: you define tasks as exports, the SDK picks them up, the platform schedules and runs them in isolated containers, and the run state is persisted so you can resume, retry, and observe.
22~
23## Getting Started
24~
25### Initialize a project
26~
27```bash
28npx trigger.dev@latest login
29npx trigger.dev@latest init
30```
31~
32This creates a `trigger.config.ts` file and a `trigger/` directory with example tasks. The config file is the source of truth for your project: which directories contain tasks, build settings, lifecycle hooks, and runtime options.
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### Run tasks locally
57~
58```bash
59npx trigger.dev@latest dev
60```
61~
62The dev server connects to the cloud, registers your tasks, and streams runs through your local code. You set breakpoints in your editor and hit them on real triggers - the same loop you would use in any normal Node.js project.
63~
64## Defining a Task
65~
66A task is an object exported with a unique `id` and a `run` function. The SDK introspects exports across `dirs` and registers them automatically.
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~
97Three things to notice:
98~
991. **No timeout in the run body.** The platform manages execution time through `maxDuration` in config, not the runtime.
1002. **Throws are retries.** The SDK catches exceptions and re-runs with exponential backoff according to the `retry` policy.
1013. **The return value is persisted.** Other tasks and your frontend can read `run.output` from anywhere.
102~
103## Triggering Tasks
104~
105You call a task from your backend, your API routes, or another 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 - use this to track or display progress
122```
123~
124The options unlock a lot of behavior in one call:
125~
126- **`idempotencyKey`** - if a run with the same key already exists, the SDK returns the existing handle instead of duplicating work.
127- **`concurrencyKey`** - serializes runs sharing the key so you do not overrun a per-tenant rate limit.
128- **`queue.concurrencyLimit`** - global cap for the queue across all keys.
129- **`delay`** - schedules the run for a future time.
130- **`ttl`** - if the run has not started by then, expire it automatically.
131~
132### Batch trigger
133~
134For fan-out workloads, `batchTrigger` accepts up to 500 items per call and creates one run per item.
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## Scheduled Tasks
146~
147Cron jobs become first-class declarations. The schedule itself is a separate object you can attach to a task multiple times.
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~
167For per-tenant schedules - say, one cron per customer - you create them dynamically through the 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~
181The `deduplicationKey` makes the call idempotent: re-running the same code at deploy time does not stack duplicate schedules.
182~
183## Queues, Concurrency, and Idempotency
184~
185Three primitives cover most rate-limiting and ordering needs.
186~
187```mermaid
188graph TB
189    Trigger[trigger payload] --> IK{idempotencyKey<br/>seen?}
190    IK -->|yes| Reuse[Return existing run]
191    IK -->|no| CK[concurrencyKey bucket]
192    CK --> Q[Queue with<br/>concurrencyLimit]
193    Q -->|slot available| Run[Run task]
194    Q -->|slots full| Wait[Wait in queue]
195```
196~
197A common pattern: a queue per tenant with a small per-key concurrency to respect a vendor's rate limit, plus an idempotency key to make retries safe.
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## Waits and Long-Running Work
211~
212Tasks can pause without holding a connection or burning compute. The platform persists state and resumes the function when the wait completes.
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` is the killer feature: it triggers a child task and suspends the parent until the child completes. You compose tasks like async functions, but the orchestration runs durably across days or weeks.
230~
231### Human-in-the-loop with `wait.forToken`
232~
233For approval flows and AI gates, `wait.forToken` pauses until your application calls back with a result.
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~
258The editor opens a UI, reviews the draft, clicks Approve, and your backend completes the token. The task picks up where it left off - even if hours or days have passed.
259~
260## Lifecycle Hooks
261~
262You can attach `init`, `onStart`, `onSuccess`, and `onFailure` to a task or globally in `trigger.config.ts`. Use these for tracing, error reporting, and shared setup.
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` runs once per worker container at boot, not per run, so it is the right place to set up clients and pools.
280~
281## Realtime in the Frontend
282~
283Trigger.dev publishes run state changes - status, metadata, output - over a streaming API. The React hooks subscribe to that stream and re-render automatically.
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~
336You generate the public access token server-side, scoped to a specific run, and ship it to the client. The hook handles auth, reconnection, and incremental updates.
337~
338For trigger-and-subscribe in one shot:
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 Agents and Streaming
354~
355Trigger.dev has become a popular runtime for AI agents because the same primitives - durable execution, retries, waits, real-time metadata, human-in-the-loop - are exactly what agents need. You stream tokens from a model provider into `metadata` while the run is happening, the frontend renders them live, and the run survives long-running tool calls without burning a serverless timeout.
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~
384The frontend uses `useRealtimeRun` and reads `run.metadata.partial` to render the streaming response, the same way you would render a chat completion - except this one survives a full page reload.
385~
386## Deploying
387~
388Deploys compile your tasks into a versioned bundle, build a container, and atomically swap traffic. Old in-flight runs keep using the previous version.
389~
390```bash
391npx trigger.dev@latest deploy --env prod
392```
393~
394In CI you typically wire this into the same workflow that ships your app:
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~
404For preview environments, pass `--env preview --branch ${{ github.head_ref }}` and Trigger.dev creates an isolated environment per branch, mirroring how Vercel handles preview deployments.
405~
406## Self-Hosting vs Cloud
407~
408Trigger.dev is open source under the Apache 2.0 license. You can self-host on any container platform (Docker Compose, Kubernetes, Fly.io) or use the managed cloud at trigger.dev.
409~
410| Aspect | Cloud | Self-hosted |
411|--------|-------|-------------|
412| **Setup** | Sign up, run `init` | Run docker-compose or Helm chart |
413| **Scaling** | Automatic | Your responsibility |
414| **Pricing** | Per run + per compute | Infra cost only |
415| **Compliance** | SOC 2 | Whatever your environment provides |
416| **Best for** | Most teams | Strict data residency, custom infra |
417~
418The SDK and CLI are identical between modes - you change a profile flag and point at your own instance.
419~
420## Best Practices
421~
422### 1. Make payloads small and serializable
423~
424Pass IDs and references, not full objects. Pull the data inside the task. This keeps the queue small, payloads cheap to log, and lets you change the data source without re-triggering.
425~
426### 2. Idempotency keys on every external call
427~
428Combine `idempotencyKey` on the task trigger with idempotency keys at your vendor APIs (Stripe, OpenAI, etc.). Retries will be safe end to end.
429~
430### 3. Use `triggerAndWait` for orchestration, not `Promise.all` of triggers
431~
432A parent that calls `triggerAndWait` durably composes child tasks. A parent that triggers and resolves immediately loses observability of the chain.
433~
434### 4. Tag runs
435~
436Add `tags` to triggers (`tags: ["user:123", "feature:onboarding"]`) so you can filter the dashboard and the management API by business dimensions.
437~
438### 5. Keep `init` idempotent
439~
440It runs on every cold start. Avoid migrations or one-shot side effects there.
441~
442## Conclusion
443~
444Trigger.dev removes the categories of work that used to require building a job system from scratch. You write async TypeScript, you call it from anywhere, and the platform gives you durable execution, scheduling, queues, retries, real-time updates, and human-in-the-loop patterns out of the box.
445~
446The same surface that powers a nightly cron is the surface that powers a multi-step AI agent that streams to the frontend and pauses for review. That convergence is what makes the framework worth a serious look in 2026, whether you are running a SaaS that needs reliable background work or shipping AI features that outlive a serverless timeout.
447~
448> **Getting Started Checklist:**
449>
450> - [x] Sign up at trigger.dev or run the self-hosted Docker stack
451> - [x] `npx trigger.dev@latest init` in your project
452> - [x] Define your first task with `task({ id, run })`
453> - [x] Trigger it from your API and watch the run in the dashboard
454> - [x] Add `idempotencyKey` and `concurrencyKey` for production safety
455> - [x] Wire `useRealtimeRun` into a status component
456> - [x] Deploy with `trigger.dev deploy --env prod` from CI
457~