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