1~
2La plupart des applications en production ont besoin de travail qui ne rentre pas dans le cycle requete/reponse : envoi d'emails, traitement d'uploads, execution de pipelines IA, synchronisation de donnees tierces, generation de rapports. La reponse traditionnelle est une queue (Redis, SQS, RabbitMQ), une flotte de workers, un scheduler et une pile fragile de code de glue qui casse a chaque deploiement.
3~
4[Trigger.dev](https://trigger.dev) reduit cette stack a un seul SDK TypeScript. Vous ecrivez des fonctions, vous les appelez de n'importe ou et la plateforme gere le queueing, les retries, l'observabilite, le scheduling et l'execution durable. Les tasks tournent aussi longtemps que necessaire - pas de timeout serverless de 10 secondes, pas de travail perdu lors des redeploys.
5~
6## Pourquoi Trigger.dev
7~
8Le changement en 2026 est l'execution durable. Les workflows doivent survivre aux redemarrages, crashes, deploiements et rate limits. Ils doivent aussi streamer le progres vers l'UI en temps reel et se mettre en pause pour l'input humain. Trigger.dev a ete reconstruit autour de ces exigences avec la version 3 et continue a etendre sa surface d'infrastructure pour l'IA.
9~
10```mermaid
11graph LR
12    App[Votre App] -->|trigger| API[API Trigger.dev]
13    API --> Queue[Queue Durable]
14    Queue --> Worker[Container Worker]
15    Worker -->|run task| Task[Code de votre Task]
16    Task -->|metadata| Realtime[Stream Realtime]
17    Realtime --> UI[UI React]
18    Worker --> Storage[Store Etat Run]
19```
20~
21Le modele est simple : vous definissez les tasks comme exports, le SDK les recupere, la plateforme les schedule et les execute dans des containers isoles et l'etat du run est persiste pour que vous puissiez reprendre, retry et observer.
22~
23## Pour commencer
24~
25### Initialiser un projet
26~
27```bash
28npx trigger.dev@latest login
29npx trigger.dev@latest init
30```
31~
32Cela cree un fichier `trigger.config.ts` et un repertoire `trigger/` avec des tasks d'exemple. Le fichier de config est la source de verite pour votre projet : quels repertoires contiennent les tasks, parametres de build, lifecycle hooks et options de runtime.
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### Executer les tasks en local
57~
58```bash
59npx trigger.dev@latest dev
60```
61~
62Le serveur de dev se connecte au cloud, enregistre vos tasks et streame les runs a travers votre code local. Vous mettez des breakpoints dans votre editeur et vous les atteignez sur de vrais triggers - la meme boucle que vous utiliseriez dans n'importe quel projet Node.js normal.
63~
64## Definir une Task
65~
66Une task est un objet exporte avec un `id` unique et une fonction `run`. Le SDK inspecte les exports a travers `dirs` et les enregistre automatiquement.
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~
97Trois choses a noter :
98~
991. **Pas de timeout dans le corps du run.** La plateforme gere le temps d'execution via `maxDuration` dans la config, pas dans le runtime.
1002. **Les throws sont des retries.** Le SDK attrape les exceptions et re-execute avec un backoff exponentiel selon la policy `retry`.
1013. **La valeur de retour est persistee.** D'autres tasks et votre frontend peuvent lire `run.output` de n'importe ou.
102~
103## Triggerer les Tasks
104~
105Vous appelez une task depuis votre backend, vos routes API ou une autre 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 - utilisez-le pour tracer ou afficher le progres
122```
123~
124Les options debloquent beaucoup de comportement en un seul appel :
125~
126- **`idempotencyKey`** - si un run avec la meme key existe deja, le SDK retourne le handle existant au lieu de dupliquer le travail.
127- **`concurrencyKey`** - serialise les runs partageant la key pour que vous ne depassiez pas un rate limit per-tenant.
128- **`queue.concurrencyLimit`** - cap global pour la queue a travers toutes les keys.
129- **`delay`** - schedule le run pour un temps futur.
130- **`ttl`** - si le run n'a pas demarre d'ici la, expirez-le automatiquement.
131~
132### Batch trigger
133~
134Pour les workloads de fan-out, `batchTrigger` accepte jusqu'a 500 items par appel et cree un run par 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## Tasks Schedules
146~
147Les cron jobs deviennent des declarations de premiere classe. Le schedule lui-meme est un objet separe que vous pouvez attacher a une task plusieurs fois.
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~
167Pour les schedules per-tenant - disons, un cron par client - vous les creez dynamiquement via la 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~
181La `deduplicationKey` rend l'appel idempotent : reexecuter le meme code au moment du deploy n'empile pas de schedules dupliques.
182~
183## Queues, Concurrence et Idempotence
184~
185Trois primitives couvrent la plupart des besoins de rate-limiting et d'ordering.
186~
187```mermaid
188graph TB
189    Trigger[trigger payload] --> IK{idempotencyKey<br/>vue?}
190    IK -->|oui| Reuse[Retourner run existant]
191    IK -->|non| CK[bucket concurrencyKey]
192    CK --> Q[Queue avec<br/>concurrencyLimit]
193    Q -->|slot disponible| Run[Executer task]
194    Q -->|slots pleins| Wait[Attendre dans la queue]
195```
196~
197Un pattern courant : une queue par tenant avec une petite concurrence per-key pour respecter le rate limit d'un vendor, plus une idempotency key pour rendre les retries surs.
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## Attentes et travail de longue duree
211~
212Les tasks peuvent se mettre en pause sans tenir une connexion ou bruler du compute. La plateforme persiste l'etat et reprend la fonction quand l'attente se termine.
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` est la feature decisive : elle triggere une task enfant et suspend le parent jusqu'a ce que l'enfant se termine. Vous composez les tasks comme des fonctions async, mais l'orchestration tourne durablement a travers des jours ou des semaines.
230~
231### Human-in-the-loop avec `wait.forToken`
232~
233Pour les flux d'approbation et les gates IA, `wait.forToken` met en pause jusqu'a ce que votre application reponde avec un resultat.
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~
258L'editeur ouvre une UI, revoit le brouillon, clique sur Approve et votre backend complete le token. La task reprend la ou elle s'etait arretee - meme si des heures ou jours sont passes.
259~
260## Lifecycle Hooks
261~
262Vous pouvez attacher `init`, `onStart`, `onSuccess` et `onFailure` a une task ou globalement dans `trigger.config.ts`. Utilisez-les pour le tracing, l'error reporting et le setup partage.
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` tourne une fois par container worker au boot, pas par run, donc c'est le bon endroit pour configurer les clients et pools.
280~
281## Realtime dans le Frontend
282~
283Trigger.dev publie les changements d'etat de run - status, metadata, output - sur une API en streaming. Les hooks React s'abonnent a ce stream et re-rendent automatiquement.
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~
336Vous generez le public access token cote serveur, scoped a un run specifique, et l'envoyez au client. Le hook gere l'auth, la reconnexion et les mises a jour incrementielles.
337~
338Pour trigger-and-subscribe en un seul coup :
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## Agents IA et Streaming
354~
355Trigger.dev est devenu un runtime populaire pour les agents IA car les memes primitives - execution durable, retries, attentes, metadata en temps reel, human-in-the-loop - sont exactement ce dont les agents ont besoin. Vous streamez les tokens d'un model provider dans `metadata` pendant que le run a lieu, le frontend les rend en direct et le run survit aux tool calls de longue duree sans bruler un timeout 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~
384Le frontend utilise `useRealtimeRun` et lit `run.metadata.partial` pour rendre la reponse en streaming, de la meme maniere que vous rendriez une chat completion - sauf que celle-ci survit a un rechargement complet de la page.
385~
386## Deploiement
387~
388Les deploys compilent vos tasks dans un bundle versionne, construisent un container et echangent atomiquement le trafic. Les anciens runs en cours continuent d'utiliser la version precedente.
389~
390```bash
391npx trigger.dev@latest deploy --env prod
392```
393~
394En CI, vous cablez typiquement cela dans le meme workflow qui livre votre 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~
404Pour les environnements de preview, passez `--env preview --branch ${{ github.head_ref }}` et Trigger.dev cree un environnement isole par branche, refletant la facon dont Vercel gere les preview deployments.
405~
406## Self-Hosting vs Cloud
407~
408Trigger.dev est open source sous la licence Apache 2.0. Vous pouvez self-hoster sur n'importe quelle plateforme de containers (Docker Compose, Kubernetes, Fly.io) ou utiliser le cloud manage sur trigger.dev.
409~
410| Aspect | Cloud | Self-hosted |
411|--------|-------|-------------|
412| **Setup** | Inscription, executer `init` | Executer docker-compose ou Helm chart |
413| **Scaling** | Automatique | Votre responsabilite |
414| **Pricing** | Par run + par compute | Cout d'infra uniquement |
415| **Compliance** | SOC 2 | Ce que fournit votre environnement |
416| **Ideal pour** | La plupart des equipes | Residence des donnees stricte, infra custom |
417~
418Le SDK et la CLI sont identiques entre les modes - vous changez un flag de profil et pointez vers votre propre instance.
419~
420## Best Practices
421~
422### 1. Gardez les payloads petits et serialisables
423~
424Passez des IDs et des references, pas des objets complets. Recuperez les donnees a l'interieur de la task. Cela garde la queue petite, les payloads peu couteux a logger et vous laisse changer la source de donnees sans re-triggerer.
425~
426### 2. Idempotency keys sur chaque appel externe
427~
428Combinez `idempotencyKey` sur le trigger de la task avec les idempotency keys aux APIs de vos vendors (Stripe, OpenAI, etc.). Les retries seront surs end-to-end.
429~
430### 3. Utilisez `triggerAndWait` pour l'orchestration, pas `Promise.all` de triggers
431~
432Un parent qui appelle `triggerAndWait` compose durablement les tasks enfants. Un parent qui triggere et resout immediatement perd l'observabilite de la chaine.
433~
434### 4. Taggez les runs
435~
436Ajoutez des `tags` aux triggers (`tags: ["user:123", "feature:onboarding"]`) pour pouvoir filtrer le dashboard et la management API par dimensions metier.
437~
438### 5. Gardez `init` idempotent
439~
440Il tourne a chaque cold start. Evitez les migrations ou les effets secondaires one-shot la-dedans.
441~
442## Conclusion
443~
444Trigger.dev supprime les categories de travail qui necessitaient autrefois de construire un systeme de jobs from scratch. Vous ecrivez du TypeScript async, vous l'appelez de n'importe ou et la plateforme vous donne l'execution durable, le scheduling, les queues, les retries, les mises a jour realtime et les patterns human-in-the-loop out of the box.
445~
446La meme surface qui alimente un cron nocturne est la surface qui alimente un agent IA multi-etapes qui streame vers le frontend et se met en pause pour la review. Cette convergence est ce qui rend le framework digne d'un regard serieux en 2026, que vous gerez un SaaS qui a besoin de travail en arriere-plan fiable ou que vous livrez des features IA qui survivent a un timeout serverless.
447~
448> **Checklist pour commencer :**
449>
450> - [x] Inscription sur trigger.dev ou execution de la stack Docker self-hosted
451> - [x] `npx trigger.dev@latest init` dans votre projet
452> - [x] Definir votre premiere task avec `task({ id, run })`
453> - [x] La triggerer depuis votre API et regarder le run dans le dashboard
454> - [x] Ajouter `idempotencyKey` et `concurrencyKey` pour la securite en production
455> - [x] Cabler `useRealtimeRun` dans un composant de status
456> - [x] Deployer avec `trigger.dev deploy --env prod` depuis CI
457~