1 
2اکثر برنامه‌های production به کاری نیاز دارند که در چرخه request/response جا نمی‌گیرد: ارسال ایمیل، پردازش آپلودها، اجرای pipeline‌های AI، همگام‌سازی داده‌های شخص ثالث، تولید گزارش. پاسخ سنتی یک صف (Redis, SQS, RabbitMQ)، یک ناوگان worker، یک scheduler و یک پشته شکننده از کد چسب است که در هر deploy می‌شکند.
3 
4[Trigger.dev](https://trigger.dev) آن stack را در یک TypeScript SDK واحد فشرده می‌کند. شما توابع را می‌نویسید، آن‌ها را از هر جایی فراخوانی می‌کنید و پلتفرم queueing، retries، observability، scheduling و اجرای پایدار را مدیریت می‌کند. Tasks تا زمانی که نیاز است اجرا می‌شوند - بدون timeout serverless 10 ثانیه‌ای، بدون کار از دست رفته در redeploy.
5 
6## چرا Trigger.dev
7 
8تغییر در 2026 اجرای پایدار است. Workflows باید از restart، crash، deploy و rate limit جان سالم به در ببرند. آن‌ها همچنین باید پیشرفت را به صورت realtime به UI استریم کنند و برای ورودی انسانی متوقف شوند. Trigger.dev در نسخه 3 حول این الزامات بازسازی شد و به گسترش سطح زیرساخت AI خود ادامه می‌دهد.
9 
10```mermaid
11graph LR
12    App[App شما] -->|trigger| API[Trigger.dev API]
13    API --> Queue[Queue پایدار]
14    Queue --> Worker[Worker Container]
15    Worker -->|run task| Task[کد Task شما]
16    Task -->|metadata| Realtime[Stream Realtime]
17    Realtime --> UI[React UI]
18    Worker --> Storage[Run State Store]
19```
20 
21مدل ساده است: tasks را به عنوان exports تعریف می‌کنید، SDK آن‌ها را برمی‌دارد، پلتفرم آن‌ها را برنامه‌ریزی و در کانتینرهای ایزوله اجرا می‌کند و وضعیت run حفظ می‌شود تا بتوانید ادامه دهید، دوباره تلاش کنید و مشاهده کنید.
22 
23## شروع
24 
25### یک پروژه را مقداردهی اولیه کنید
26 
27```bash
28npx trigger.dev@latest login
29npx trigger.dev@latest init
30```
31 
32این یک فایل `trigger.config.ts` و یک دایرکتوری `trigger/` با tasks نمونه ایجاد می‌کند. فایل config منبع حقیقت برای پروژه شماست: کدام دایرکتوری‌ها حاوی tasks هستند، تنظیمات build، lifecycle hooks و گزینه‌های 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### tasks را به صورت محلی اجرا کنید
57 
58```bash
59npx trigger.dev@latest dev
60```
61 
62سرور dev به cloud متصل می‌شود، tasks شما را ثبت می‌کند و runs را از طریق کد محلی شما استریم می‌کند. در ویرایشگر خود breakpoint می‌گذارید و آن‌ها را روی triggerهای واقعی می‌زنید - همان loop که در هر پروژه عادی Node.js استفاده می‌کنید.
63 
64## تعریف یک Task
65 
66Task یک شیء است که با `id` منحصر به فرد و یک تابع `run` صادر می‌شود. SDK exports را در `dirs` بررسی می‌کند و آن‌ها را به طور خودکار ثبت می‌کند.
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 
97سه نکته که باید توجه کنید:
98 
991. **بدون timeout در بدنه run.** پلتفرم زمان اجرا را از طریق `maxDuration` در config مدیریت می‌کند، نه در runtime.
1002. **Throws‌ها retries هستند.** SDK exception‌ها را می‌گیرد و طبق سیاست `retry` با backoff نمایی دوباره اجرا می‌کند.
1013. **مقدار بازگشتی حفظ می‌شود.** سایر tasks و frontend شما می‌توانند `run.output` را از هر جایی بخوانند.
102 
103## Triggering Tasks
104 
105شما task را از backend خود، route‌های API یا 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 - برای ردیابی یا نمایش پیشرفت استفاده کنید
122```
123 
124گزینه‌ها رفتار زیادی را در یک فراخوانی باز می‌کنند:
125 
126- **`idempotencyKey`** - اگر run با همان کلید قبلاً وجود داشته باشد، SDK handle موجود را بازمی‌گرداند به جای تکرار کار.
127- **`concurrencyKey`** - runs که کلید را به اشتراک می‌گذارند را سریالی می‌کند تا از rate limit per-tenant فراتر نروید.
128- **`queue.concurrencyLimit`** - cap جهانی برای queue در همه کلیدها.
129- **`delay`** - run را برای زمان آینده برنامه‌ریزی می‌کند.
130- **`ttl`** - اگر run تا آن زمان شروع نشده باشد، به طور خودکار منقضی می‌شود.
131 
132### Batch trigger
133 
134برای workload‌های fan-out، `batchTrigger` تا 500 آیتم در هر فراخوانی می‌پذیرد و یک run در هر آیتم ایجاد می‌کند.
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 زمانبندی شده
146 
147Cron job‌ها به اعلان‌های کلاس اول تبدیل می‌شوند. خود schedule یک شیء جداگانه است که می‌توانید چندین بار به یک task متصل کنید.
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 
167برای schedule‌های per-tenant - بگوییم یک cron در هر مشتری - آن‌ها را به صورت پویا از طریق 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 
181`deduplicationKey` فراخوانی را idempotent می‌کند: اجرای مجدد همان کد در زمان deploy schedule‌های تکراری را روی هم انباشته نمی‌کند.
182 
183## Queues, Concurrency و Idempotency
184 
185سه primitive اکثر نیازهای rate-limiting و ordering را پوشش می‌دهند.
186 
187```mermaid
188graph TB
189    Trigger[trigger payload] --> IK{idempotencyKey<br/>دیده شده؟}
190    IK -->|بله| Reuse[بازگشت run موجود]
191    IK -->|خیر| CK[bucket concurrencyKey]
192    CK --> Q[Queue با<br/>concurrencyLimit]
193    Q -->|slot در دسترس| Run[اجرای task]
194    Q -->|slots پر| Wait[انتظار در queue]
195```
196 
197یک الگوی رایج: یک queue به ازای هر tenant با concurrency کوچک per-key برای رعایت rate limit یک vendor، به علاوه یک کلید idempotency برای ایمن کردن retries.
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 و کار طولانی‌مدت
211 
212Tasks می‌توانند بدون نگه داشتن اتصال یا سوزاندن compute متوقف شوند. پلتفرم state را حفظ می‌کند و وقتی wait کامل شد تابع را از سر می‌گیرد.
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` ویژگی کشنده است: یک child task را trigger می‌کند و parent را تا زمانی که child تمام شود معلق می‌کند. tasks را مانند توابع async می‌نویسید، اما orchestration به طور پایدار در طول روزها یا هفته‌ها اجرا می‌شود.
230 
231### Human-in-the-loop با `wait.forToken`
232 
233برای جریان‌های تأیید و gate‌های AI، `wait.forToken` متوقف می‌شود تا برنامه شما با یک نتیجه callback کند.
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 
258ویرایشگر یک UI باز می‌کند، پیش‌نویس را بررسی می‌کند، روی Approve کلیک می‌کند و backend شما token را تکمیل می‌کند. task از جایی که متوقف شد ادامه می‌دهد - حتی اگر ساعت‌ها یا روزها گذشته باشد.
259 
260## Lifecycle Hooks
261 
262می‌توانید `init`, `onStart`, `onSuccess` و `onFailure` را به یک task یا به طور سراسری در `trigger.config.ts` متصل کنید. از آن‌ها برای tracing, error reporting و 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` یک بار در هر worker container در boot اجرا می‌شود، نه در هر run، بنابراین جای مناسبی برای تنظیم clients و pool‌ها است.
280 
281## Realtime در Frontend
282 
283Trigger.dev تغییرات وضعیت run - status, metadata, output - را از طریق streaming API منتشر می‌کند. React hooks در آن stream مشترک می‌شوند و به طور خودکار re-render می‌کنند.
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 
336شما public access token را در سمت سرور تولید می‌کنید، scoped به یک run خاص، و آن را به client ارسال می‌کنید. hook auth، اتصال مجدد و به‌روزرسانی‌های افزایشی را مدیریت می‌کند.
337 
338برای trigger-and-subscribe در یک قدم:
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 و Streaming
354 
355Trigger.dev به یک runtime محبوب برای AI agents تبدیل شده است زیرا همان primitives - اجرای پایدار، retries، waits، realtime metadata، human-in-the-loop - دقیقاً چیزی است که agents به آن نیاز دارند. token‌ها را از یک ارائه‌دهنده مدل به `metadata` در حالی که run در حال انجام است stream می‌کنید، frontend آن‌ها را به صورت زنده render می‌کند و run بدون سوزاندن timeout serverless از tool call‌های طولانی‌مدت جان سالم به در می‌برد.
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 
384frontend از `useRealtimeRun` استفاده می‌کند و `run.metadata.partial` را برای render پاسخ streaming می‌خواند، به همان روشی که یک chat completion را render می‌کردید - با این تفاوت که این یکی از reload کامل صفحه جان سالم به در می‌برد.
385 
386## Deploying
387 
388Deploy‌ها tasks شما را به یک bundle ورژن‌دار کامپایل می‌کنند، یک container می‌سازند و ترافیک را به صورت اتمیک تعویض می‌کنند. runs قدیمی in-flight به استفاده از نسخه قبلی ادامه می‌دهند.
389 
390```bash
391npx trigger.dev@latest deploy --env prod
392```
393 
394در CI معمولاً این را به همان workflow متصل می‌کنید که 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 
404برای محیط‌های preview، `--env preview --branch ${{ github.head_ref }}` را عبور دهید و Trigger.dev یک محیط ایزوله در هر branch ایجاد می‌کند، که نحوه برخورد Vercel با preview deploymentها را منعکس می‌کند.
405 
406## Self-Hosting در مقابل Cloud
407 
408Trigger.dev تحت لایسنس Apache 2.0 متن‌باز است. می‌توانید روی هر پلتفرم container (Docker Compose, Kubernetes, Fly.io) self-host کنید یا از cloud مدیریت‌شده در trigger.dev استفاده کنید.
409 
410| جنبه | Cloud | Self-hosted |
411|--------|-------|-------------|
412| **Setup** | ثبت‌نام، اجرای `init` | اجرای docker-compose یا Helm chart |
413| **Scaling** | خودکار | مسئولیت شما |
414| **Pricing** | به ازای run + به ازای compute | فقط هزینه infra |
415| **Compliance** | SOC 2 | هرچه محیط شما فراهم می‌کند |
416| **بهترین برای** | اکثر تیم‌ها | residency داده سختگیرانه، infra سفارشی |
417 
418SDK و CLI بین حالت‌ها یکسان هستند - یک profile flag را تغییر می‌دهید و به instance خود اشاره می‌کنید.
419 
420## Best Practices
421 
422### 1. payloads را کوچک و قابل serialize نگه دارید
423 
424ID‌ها و reference‌ها را عبور دهید، نه اشیاء کامل. داده‌ها را در داخل task بگیرید. این queue را کوچک نگه می‌دارد، payloads را برای log کردن ارزان می‌کند و به شما اجازه می‌دهد منبع داده را بدون trigger مجدد تغییر دهید.
425 
426### 2. کلیدهای Idempotency در هر فراخوانی خارجی
427 
428`idempotencyKey` در trigger task را با کلیدهای idempotency در API‌های vendor خود (Stripe, OpenAI, و غیره) ترکیب کنید. retries‌ها end-to-end ایمن خواهند بود.
429 
430### 3. از `triggerAndWait` برای orchestration استفاده کنید، نه `Promise.all` از trigger‌ها
431 
432یک parent که `triggerAndWait` را فراخوانی می‌کند به طور پایدار child tasks را compose می‌کند. یک parent که trigger می‌کند و فوراً resolve می‌شود، observability زنجیره را از دست می‌دهد.
433 
434### 4. runs را tag کنید
435 
436به trigger‌ها `tags` اضافه کنید (`tags: ["user:123", "feature:onboarding"]`) تا بتوانید dashboard و management API را بر اساس ابعاد business فیلتر کنید.
437 
438### 5. `init` را idempotent نگه دارید
439 
440در هر cold start اجرا می‌شود. از migrations یا اثرات جانبی one-shot در آنجا اجتناب کنید.
441 
442## نتیجه‌گیری
443 
444Trigger.dev دسته‌های کاری را که قبلاً برای ساختن یک سیستم job از صفر مورد نیاز بودند، حذف می‌کند. async TypeScript می‌نویسید، آن را از هر جایی فراخوانی می‌کنید و پلتفرم به شما اجرای پایدار، scheduling، queues، retries، به‌روزرسانی‌های realtime و الگوهای human-in-the-loop را به صورت out of the box می‌دهد.
445 
446همان سطحی که یک cron شبانه را قدرت می‌دهد، سطحی است که یک AI agent چند مرحله‌ای را قدرت می‌دهد که به frontend stream می‌کند و برای review متوقف می‌شود. این همگرایی است که framework را در 2026 شایسته یک نگاه جدی می‌کند، چه یک SaaS را اداره می‌کنید که به کار پس‌زمینه قابل اعتماد نیاز دارد، چه ویژگی‌های AI را ارسال می‌کنید که از یک serverless timeout جان سالم به در می‌برند.
447 
448> **چک‌لیست شروع:**
449>
450> - [x] در trigger.dev ثبت‌نام کنید یا stack Docker self-hosted را اجرا کنید
451> - [x] `npx trigger.dev@latest init` در پروژه شما
452> - [x] اولین task خود را با `task({ id, run })` تعریف کنید
453> - [x] آن را از API خود trigger کنید و run را در dashboard ببینید
454> - [x] برای امنیت production `idempotencyKey` و `concurrencyKey` اضافه کنید
455> - [x] `useRealtimeRun` را به یک status component متصل کنید
456> - [x] با `trigger.dev deploy --env prod` از CI deploy کنید
457