1~
2La mayoria de las aplicaciones en produccion necesitan trabajo que no encaja en el ciclo peticion/respuesta: enviar emails, procesar uploads, ejecutar pipelines de IA, sincronizar datos de terceros, generar reportes. La respuesta tradicional es una cola (Redis, SQS, RabbitMQ), una flota de workers, un scheduler y una pila fragil de codigo glue que se rompe en cada deploy.
3~
4[Trigger.dev](https://trigger.dev) colapsa esa stack en un unico SDK de TypeScript. Escribes funciones, las llamas desde cualquier lugar y la plataforma maneja el queueing, los retries, la observabilidad, el scheduling y la ejecucion duradera. Las tasks corren todo el tiempo necesario - sin timeout serverless de 10 segundos, sin trabajo perdido en redeploys.
5~
6## Por que Trigger.dev
7~
8El cambio en 2026 es la ejecucion duradera. Los workflows deben sobrevivir a reinicios, crashes, deploys y rate limits. Tambien deben streamear el progreso a la UI en tiempo real y pausarse para input humano. Trigger.dev fue reconstruido alrededor de estos requisitos con la version 3 y continua expandiendo su superficie de infraestructura para IA.
9~
10```mermaid
11graph LR
12    App[Tu App] -->|trigger| API[API Trigger.dev]
13    API --> Queue[Cola Duradera]
14    Queue --> Worker[Container Worker]
15    Worker -->|run task| Task[Codigo de tu Task]
16    Task -->|metadata| Realtime[Stream Realtime]
17    Realtime --> UI[UI React]
18    Worker --> Storage[Store Estado Run]
19```
20~
21El modelo es simple: defines tasks como exports, el SDK las recoge, la plataforma las planifica y ejecuta en containers aislados y el estado del run se persiste para que puedas reanudar, reintentar y observar.
22~
23## Para empezar
24~
25### Inicializar un proyecto
26~
27```bash
28npx trigger.dev@latest login
29npx trigger.dev@latest init
30```
31~
32Esto crea un archivo `trigger.config.ts` y un directorio `trigger/` con tasks de ejemplo. El archivo de config es la fuente de verdad para tu proyecto: que directorios contienen tasks, ajustes de build, lifecycle hooks y opciones 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### Ejecutar tasks localmente
57~
58```bash
59npx trigger.dev@latest dev
60```
61~
62El servidor de dev se conecta a la cloud, registra tus tasks y streamea los runs a traves de tu codigo local. Pones breakpoints en tu editor y los alcanzas con triggers reales - el mismo loop que usarias en cualquier proyecto Node.js normal.
63~
64## Definir una Task
65~
66Una task es un objeto exportado con un `id` unico y una funcion `run`. El SDK inspecciona los exports a traves de `dirs` y los registra automaticamente.
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~
97Tres cosas a notar:
98~
991. **Sin timeout en el cuerpo del run.** La plataforma gestiona el tiempo de ejecucion via `maxDuration` en config, no en el runtime.
1002. **Los throws son retries.** El SDK captura excepciones y reejecuta con backoff exponencial segun la policy `retry`.
1013. **El valor de retorno se persiste.** Otras tasks y tu frontend pueden leer `run.output` desde cualquier lugar.
102~
103## Triggerear Tasks
104~
105Llamas a una task desde tu backend, tus rutas API u otra 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 - usalo para rastrear o mostrar el progreso
122```
123~
124Las opciones desbloquean mucho comportamiento en una sola llamada:
125~
126- **`idempotencyKey`** - si un run con la misma key ya existe, el SDK retorna el handle existente en vez de duplicar trabajo.
127- **`concurrencyKey`** - serializa runs que comparten la key para que no excedas un rate limit per-tenant.
128- **`queue.concurrencyLimit`** - cap global para la cola a traves de todas las keys.
129- **`delay`** - planifica el run para un tiempo futuro.
130- **`ttl`** - si el run no ha empezado para entonces, expiralo automaticamente.
131~
132### Batch trigger
133~
134Para workloads de fan-out, `batchTrigger` acepta hasta 500 items por llamada y crea un run por 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 Programadas
146~
147Los cron jobs se vuelven declaraciones de primera clase. El schedule en si es un objeto separado que puedes adjuntar a una task multiples veces.
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~
167Para schedules per-tenant - digamos, un cron por cliente - los creas dinamicamente a traves de 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` hace la llamada idempotente: reejecutar el mismo codigo en deploy time no apila schedules duplicados.
182~
183## Colas, Concurrencia e Idempotencia
184~
185Tres primitivas cubren la mayoria de las necesidades de rate-limiting y ordering.
186~
187```mermaid
188graph TB
189    Trigger[trigger payload] --> IK{idempotencyKey<br/>vista?}
190    IK -->|si| Reuse[Retornar run existente]
191    IK -->|no| CK[bucket concurrencyKey]
192    CK --> Q[Cola con<br/>concurrencyLimit]
193    Q -->|slot disponible| Run[Ejecutar task]
194    Q -->|slots llenos| Wait[Esperar en cola]
195```
196~
197Un patron comun: una cola por tenant con una pequena concurrencia per-key para respetar el rate limit de un vendor, mas una idempotency key para hacer los retries seguros.
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## Esperas y Trabajo de Larga Duracion
211~
212Las tasks pueden pausarse sin mantener una conexion o quemar compute. La plataforma persiste el estado y reanuda la funcion cuando la espera se completa.
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` es la feature decisiva: triggea una task hijo y suspende al padre hasta que el hijo se completa. Compones tasks como funciones async, pero la orquestacion corre duraderamente a traves de dias o semanas.
230~
231### Human-in-the-loop con `wait.forToken`
232~
233Para flujos de aprobacion y gates de IA, `wait.forToken` pausa hasta que tu aplicacion responda con un resultado.
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~
258El editor abre una UI, revisa el borrador, hace clic en Aprobar y tu backend completa el token. La task continua donde se quedo - incluso si han pasado horas o dias.
259~
260## Lifecycle Hooks
261~
262Puedes adjuntar `init`, `onStart`, `onSuccess` y `onFailure` a una task o globalmente en `trigger.config.ts`. Usalos para tracing, error reporting y setup compartido.
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` corre una vez por container worker en el boot, no por run, asi que es el lugar correcto para configurar clientes y pools.
280~
281## Realtime en el Frontend
282~
283Trigger.dev publica los cambios de estado del run - status, metadata, output - sobre una API en streaming. Los hooks React se suscriben a ese stream y rerenderizan automaticamente.
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~
336Generas el public access token del lado del servidor, scoped a un run especifico, y lo envias al cliente. El hook maneja auth, reconexion y actualizaciones incrementales.
337~
338Para trigger-and-subscribe en un solo paso:
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## Agentes IA y Streaming
354~
355Trigger.dev se ha convertido en un runtime popular para agentes IA porque las mismas primitivas - ejecucion duradera, retries, esperas, metadata en tiempo real, human-in-the-loop - son exactamente lo que los agentes necesitan. Streameas tokens de un proveedor de modelos a `metadata` mientras el run esta sucediendo, el frontend los renderiza en vivo y el run sobrevive a tool calls de larga duracion sin quemar 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~
384El frontend usa `useRealtimeRun` y lee `run.metadata.partial` para renderizar la respuesta en streaming, de la misma forma en que renderizarias una chat completion - excepto que esta sobrevive a una recarga completa de la pagina.
385~
386## Deployando
387~
388Los deploys compilan tus tasks a un bundle versionado, construyen un container y hacen swap atomico del trafico. Los runs viejos en vuelo siguen usando la version anterior.
389~
390```bash
391npx trigger.dev@latest deploy --env prod
392```
393~
394En CI tipicamente conectas esto al mismo workflow que envia tu 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~
404Para entornos de preview, pasa `--env preview --branch ${{ github.head_ref }}` y Trigger.dev crea un entorno aislado por branch, reflejando como Vercel maneja los preview deployments.
405~
406## Self-Hosting vs Cloud
407~
408Trigger.dev es open source bajo la licencia Apache 2.0. Puedes self-hostear en cualquier plataforma de containers (Docker Compose, Kubernetes, Fly.io) o usar la cloud gestionada en trigger.dev.
409~
410| Aspecto | Cloud | Self-hosted |
411|--------|-------|-------------|
412| **Setup** | Registrarse, ejecutar `init` | Ejecutar docker-compose o Helm chart |
413| **Scaling** | Automatico | Tu responsabilidad |
414| **Pricing** | Por run + por compute | Solo costo de infra |
415| **Compliance** | SOC 2 | Lo que provee tu entorno |
416| **Ideal para** | La mayoria de los equipos | Residencia de datos estricta, infra custom |
417~
418El SDK y la CLI son identicos entre modos - cambias un flag de perfil y apuntas a tu propia instancia.
419~
420## Best Practices
421~
422### 1. Manten los payloads pequenos y serializables
423~
424Pasa IDs y referencias, no objetos completos. Recupera los datos dentro de la task. Esto mantiene la cola pequena, los payloads baratos de loggear y te deja cambiar la fuente de datos sin retriggerear.
425~
426### 2. Idempotency keys en cada llamada externa
427~
428Combina `idempotencyKey` en el trigger de la task con idempotency keys en las APIs de tus vendors (Stripe, OpenAI, etc.). Los retries seran seguros end-to-end.
429~
430### 3. Usa `triggerAndWait` para orquestacion, no `Promise.all` de triggers
431~
432Un padre que llama a `triggerAndWait` compone duraderamente las tasks hijos. Un padre que triggea y resuelve inmediatamente pierde la observabilidad de la cadena.
433~
434### 4. Tagea los runs
435~
436Anade `tags` a los triggers (`tags: ["user:123", "feature:onboarding"]`) para poder filtrar el dashboard y la management API por dimensiones de negocio.
437~
438### 5. Manten `init` idempotente
439~
440Corre en cada cold start. Evita migraciones o efectos secundarios one-shot ahi.
441~
442## Conclusion
443~
444Trigger.dev elimina las categorias de trabajo que solian requerir construir un sistema de jobs desde cero. Escribes TypeScript async, lo llamas desde cualquier lugar y la plataforma te da ejecucion duradera, scheduling, colas, retries, actualizaciones en tiempo real y patrones human-in-the-loop out of the box.
445~
446La misma superficie que alimenta un cron nocturno es la superficie que alimenta un agente IA multi-paso que streamea al frontend y pausa para revision. Esa convergencia es lo que hace al framework digno de una mirada seria en 2026, ya sea que estes manejando un SaaS que necesita trabajo en segundo plano confiable o enviando features de IA que sobreviven a un timeout serverless.
447~
448> **Checklist para empezar:**
449>
450> - [x] Registrate en trigger.dev o ejecuta el stack Docker self-hosted
451> - [x] `npx trigger.dev@latest init` en tu proyecto
452> - [x] Define tu primera task con `task({ id, run })`
453> - [x] Triggeala desde tu API y mira el run en el dashboard
454> - [x] Anade `idempotencyKey` y `concurrencyKey` para la seguridad en produccion
455> - [x] Conecta `useRealtimeRun` en un componente de status
456> - [x] Deploya con `trigger.dev deploy --env prod` desde CI
457~