1~
2Die meisten Produktionsanwendungen brauchen Arbeit, die nicht in den Request/Response-Zyklus passt: E-Mails versenden, Uploads verarbeiten, KI-Pipelines ausfuhren, Drittanbieter-Daten synchronisieren, Berichte generieren. Die traditionelle Antwort ist eine Queue (Redis, SQS, RabbitMQ), eine Worker-Flotte, ein Scheduler und ein zerbrechlicher Stapel von Glue-Code, der bei jedem Deploy bricht.
3~
4[Trigger.dev](https://trigger.dev) kollabiert diesen Stack in ein einziges TypeScript-SDK. Du schreibst Funktionen, rufst sie von uberall auf und die Plattform verwaltet Queueing, Retries, Observability, Scheduling und durable Execution. Tasks laufen so lange wie notig - kein 10-Sekunden-Serverless-Timeout, kein verlorenes Werk bei Redeploys.
5~
6## Warum Trigger.dev
7~
8Die Verschiebung 2026 ist Durable Execution. Workflows mussen Restarts, Crashes, Deploys und Rate Limits uberleben. Sie mussen auch Fortschritt in Echtzeit zur UI streamen und fur menschliche Eingaben pausieren. Trigger.dev wurde mit Version 3 um diese Anforderungen herum neu gebaut und erweitert weiterhin seine KI-Infrastruktur-Oberflache.
9~
10```mermaid
11graph LR
12    App[Deine App] -->|trigger| API[Trigger.dev API]
13    API --> Queue[Durable Queue]
14    Queue --> Worker[Worker Container]
15    Worker -->|run task| Task[Dein Task-Code]
16    Task -->|metadata| Realtime[Realtime Stream]
17    Realtime --> UI[React UI]
18    Worker --> Storage[Run State Store]
19```
20~
21Das Modell ist einfach: du definierst Tasks als Exports, das SDK nimmt sie auf, die Plattform plant und fuhrt sie in isolierten Containern aus und der Run-Status wird persistiert, sodass du fortsetzen, wiederholen und beobachten kannst.
22~
23## Loslegen
24~
25### Projekt initialisieren
26~
27```bash
28npx trigger.dev@latest login
29npx trigger.dev@latest init
30```
31~
32Das erstellt eine `trigger.config.ts`-Datei und ein `trigger/`-Verzeichnis mit Beispiel-Tasks. Die Config-Datei ist die Source of Truth fur dein Projekt: welche Verzeichnisse Tasks enthalten, Build-Einstellungen, Lifecycle-Hooks und Runtime-Optionen.
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 lokal ausfuhren
57~
58```bash
59npx trigger.dev@latest dev
60```
61~
62Der Dev-Server verbindet sich mit der Cloud, registriert deine Tasks und streamt Runs durch deinen lokalen Code. Du setzt Breakpoints in deinem Editor und triffst sie bei echten Triggers - dieselbe Schleife, die du in jedem normalen Node.js-Projekt verwenden wurdest.
63~
64## Einen Task definieren
65~
66Ein Task ist ein Objekt, das mit einer eindeutigen `id` und einer `run`-Funktion exportiert wird. Das SDK inspiziert Exports uber `dirs` und registriert sie automatisch.
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~
97Drei Dinge zu beachten:
98~
991. **Kein Timeout im Run-Body.** Die Plattform verwaltet die Ausfuhrungszeit uber `maxDuration` in der Config, nicht zur Laufzeit.
1002. **Throws sind Retries.** Das SDK fangt Exceptions ab und fuhrt erneut mit exponentiellem Backoff gemass der `retry`-Policy aus.
1013. **Der Ruckgabewert wird persistiert.** Andere Tasks und dein Frontend konnen `run.output` von uberall lesen.
102~
103## Tasks triggern
104~
105Du rufst einen Task von deinem Backend, deinen API-Routen oder einem anderen Task auf.
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 - verwende dies, um Fortschritt zu verfolgen oder anzuzeigen
122```
123~
124Die Optionen entsperren in einem Aufruf viel Verhalten:
125~
126- **`idempotencyKey`** - existiert bereits ein Run mit demselben Key, gibt das SDK das vorhandene Handle zuruck, statt Arbeit zu duplizieren.
127- **`concurrencyKey`** - serialisiert Runs, die den Key teilen, sodass du kein per-Tenant-Rate-Limit uberschreitest.
128- **`queue.concurrencyLimit`** - globaler Cap fur die Queue uber alle Keys.
129- **`delay`** - plant den Run fur eine zukunftige Zeit.
130- **`ttl`** - wenn der Run bis dahin nicht gestartet ist, lass ihn automatisch ablaufen.
131~
132### Batch-Trigger
133~
134Fur Fan-Out-Workloads akzeptiert `batchTrigger` bis zu 500 Items pro Aufruf und erstellt einen Run pro 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## Geplante Tasks
146~
147Cron-Jobs werden zu erstklassigen Deklarationen. Der Schedule selbst ist ein separates Objekt, das du mehrfach an einen Task anhangen kannst.
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~
167Fur per-Tenant-Schedules - sagen wir, ein Cron pro Kunde - erstellst du sie dynamisch uber die 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~
181Der `deduplicationKey` macht den Aufruf idempotent: dasselben Code zur Deploy-Zeit erneut auszufuhren, stapelt keine doppelten Schedules.
182~
183## Queues, Concurrency und Idempotenz
184~
185Drei Primitive decken die meisten Rate-Limiting- und Ordering-Bedurfnisse ab.
186~
187```mermaid
188graph TB
189    Trigger[trigger payload] --> IK{idempotencyKey<br/>gesehen?}
190    IK -->|ja| Reuse[Existierenden Run zuruckgeben]
191    IK -->|nein| CK[concurrencyKey Bucket]
192    CK --> Q[Queue mit<br/>concurrencyLimit]
193    Q -->|Slot frei| Run[Task ausfuhren]
194    Q -->|Slots voll| Wait[In Queue warten]
195```
196~
197Ein gangiges Pattern: eine Queue pro Tenant mit einer kleinen per-Key-Concurrency, um das Rate-Limit eines Vendors zu respektieren, plus ein Idempotency-Key, um Retries sicher zu machen.
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 und langlaufende Arbeit
211~
212Tasks konnen pausieren, ohne eine Verbindung zu halten oder Compute zu verbrennen. Die Plattform persistiert den State und setzt die Funktion fort, wenn der Wait abgeschlossen ist.
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` ist das Killer-Feature: es triggert einen Child-Task und suspendiert den Parent, bis der Child abgeschlossen ist. Du komponierst Tasks wie async-Funktionen, aber die Orchestrierung lauft durable uber Tage oder Wochen.
230~
231### Human-in-the-Loop mit `wait.forToken`
232~
233Fur Approval-Flows und KI-Gates pausiert `wait.forToken`, bis deine Anwendung mit einem Ergebnis zuruckruft.
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~
258Der Editor offnet eine UI, uberpruft den Entwurf, klickt auf Approve und dein Backend schliesst das Token ab. Der Task setzt dort fort, wo er aufgehort hat - selbst wenn Stunden oder Tage vergangen sind.
259~
260## Lifecycle-Hooks
261~
262Du kannst `init`, `onStart`, `onSuccess` und `onFailure` an einen Task oder global in `trigger.config.ts` anhangen. Verwende sie fur Tracing, Error-Reporting und gemeinsames 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` lauft einmal pro Worker-Container beim Boot, nicht pro Run, also ist es der richtige Ort, um Clients und Pools einzurichten.
280~
281## Realtime im Frontend
282~
283Trigger.dev publiziert Run-State-Anderungen - Status, Metadaten, Output - uber eine Streaming-API. Die React-Hooks abonnieren diesen Stream und re-rendern automatisch.
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~
336Du generierst das Public-Access-Token serverseitig, scoped auf einen bestimmten Run, und schickst es an den Client. Der Hook verwaltet Auth, Reconnection und inkrementelle Updates.
337~
338Fur Trigger-and-Subscribe in einem Schritt:
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## KI-Agenten und Streaming
354~
355Trigger.dev ist eine beliebte Runtime fur KI-Agenten geworden, weil dieselben Primitive - durable Execution, Retries, Waits, Echtzeit-Metadaten, Human-in-the-Loop - genau das sind, was Agenten brauchen. Du streamst Tokens von einem Modell-Provider in `metadata`, wahrend der Run lauft, das Frontend rendert sie live und der Run uberlebt langlaufende Tool-Calls, ohne ein Serverless-Timeout zu verbrennen.
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~
384Das Frontend verwendet `useRealtimeRun` und liest `run.metadata.partial`, um die Streaming-Antwort zu rendern, genauso wie du eine Chat-Completion rendern wurdest - ausser, dass diese einen vollstandigen Page-Reload uberlebt.
385~
386## Deployen
387~
388Deploys kompilieren deine Tasks zu einem versionierten Bundle, bauen einen Container und tauschen den Verkehr atomar. Alte In-Flight-Runs verwenden weiterhin die vorherige Version.
389~
390```bash
391npx trigger.dev@latest deploy --env prod
392```
393~
394In CI verbindest du dies typischerweise mit demselben Workflow, der deine App ausliefert:
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~
404Fur Preview-Umgebungen ubergib `--env preview --branch ${{ github.head_ref }}` und Trigger.dev erstellt eine isolierte Umgebung pro Branch, die widerspiegelt, wie Vercel Preview-Deployments handhabt.
405~
406## Self-Hosting vs Cloud
407~
408Trigger.dev ist Open Source unter der Apache-2.0-Lizenz. Du kannst auf jeder Container-Plattform self-hosten (Docker Compose, Kubernetes, Fly.io) oder die verwaltete Cloud auf trigger.dev verwenden.
409~
410| Aspekt | Cloud | Self-hosted |
411|--------|-------|-------------|
412| **Setup** | Anmelden, `init` ausfuhren | Docker-Compose oder Helm-Chart ausfuhren |
413| **Scaling** | Automatisch | Deine Verantwortung |
414| **Pricing** | Pro Run + pro Compute | Nur Infra-Kosten |
415| **Compliance** | SOC 2 | Was deine Umgebung bietet |
416| **Ideal fur** | Die meisten Teams | Strenge Datenresidenz, Custom-Infra |
417~
418Das SDK und die CLI sind zwischen den Modi identisch - du anderst ein Profil-Flag und zeigst auf deine eigene Instanz.
419~
420## Best Practices
421~
422### 1. Halte Payloads klein und serialisierbar
423~
424Ubergib IDs und Referenzen, keine vollstandigen Objekte. Lade die Daten innerhalb des Tasks. Das halt die Queue klein, Payloads sind gunstig zu loggen und du kannst die Datenquelle andern, ohne erneut zu triggern.
425~
426### 2. Idempotency-Keys bei jedem externen Call
427~
428Kombiniere `idempotencyKey` beim Task-Trigger mit Idempotency-Keys bei deinen Vendor-APIs (Stripe, OpenAI, etc.). Retries sind end-to-end sicher.
429~
430### 3. Verwende `triggerAndWait` fur Orchestrierung, nicht `Promise.all` von Triggers
431~
432Ein Parent, der `triggerAndWait` aufruft, komponiert durable Child-Tasks. Ein Parent, der triggert und sofort auflost, verliert die Observability der Kette.
433~
434### 4. Tagge Runs
435~
436Fuge Triggers `tags` hinzu (`tags: ["user:123", "feature:onboarding"]`), damit du das Dashboard und die Management-API nach Geschaftsdimensionen filtern kannst.
437~
438### 5. Halte `init` idempotent
439~
440Es lauft bei jedem Cold Start. Vermeide Migrationen oder One-Shot-Seiteneffekte dort.
441~
442## Fazit
443~
444Trigger.dev entfernt die Kategorien von Arbeit, fur die fruher ein Job-System von Grund auf gebaut werden musste. Du schreibst async TypeScript, rufst es von uberall auf und die Plattform gibt dir durable Execution, Scheduling, Queues, Retries, Echtzeit-Updates und Human-in-the-Loop-Patterns out of the Box.
445~
446Dieselbe Oberflache, die einen nachtlichen Cron antreibt, ist die Oberflache, die einen mehrstufigen KI-Agenten antreibt, der zum Frontend streamt und fur Review pausiert. Diese Konvergenz ist das, was das Framework 2026 einer ernsthaften Betrachtung wert macht, egal ob du ein SaaS betreibst, das zuverlassige Hintergrundarbeit braucht, oder KI-Features auslieferst, die ein Serverless-Timeout uberleben.
447~
448> **Loslege-Checkliste:**
449>
450> - [x] Bei trigger.dev anmelden oder den self-hosted Docker-Stack ausfuhren
451> - [x] `npx trigger.dev@latest init` in deinem Projekt
452> - [x] Definiere deinen ersten Task mit `task({ id, run })`
453> - [x] Triggere ihn aus deiner API und beobachte den Run im Dashboard
454> - [x] Fuge `idempotencyKey` und `concurrencyKey` fur Produktionssicherheit hinzu
455> - [x] Verbinde `useRealtimeRun` mit einer Status-Komponente
456> - [x] Deploye mit `trigger.dev deploy --env prod` aus CI
457~