English Vocabulary for Trigger.dev Developers

Trigger.dev is an open-source background job and workflow platform built for TypeScript developers. It lets you write long-running, reliable background tasks as regular TypeScript functions — with built-in retries, delays, scheduling, and a visual run dashboard — without managing queues or worker processes. Trigger.dev v3 runs tasks in a serverless model on its cloud or in your own infrastructure. If your team uses Trigger.dev for background processing, understanding its vocabulary is essential for writing tasks correctly, monitoring runs in the dashboard, and discussing reliability patterns with colleagues. This post covers the core Trigger.dev terms.

Key Vocabulary

task() The core function for defining a Trigger.dev background task. You call task() with a configuration object (containing the task id) and a run function that implements the task logic. The run function receives the payload and a context object (ctx). Example: “Define a task() with id send-welcome-email and implement the email sending logic in the run function — Trigger.dev will handle queueing, retries, and logging automatically.”

trigger() The method used to enqueue a task for execution — sending it to Trigger.dev’s queue so it runs in the background. You call yourTask.trigger(payload) from your application code (e.g., in an API route handler) to initiate a task run without waiting for it to complete. Example: “Call processOrderTask.trigger({ orderId: order.id }) inside the checkout API handler — the response returns immediately while the order processing runs in the background.”

batch() A method for triggering multiple task runs at once — sending an array of payloads in a single API call. More efficient than calling trigger() in a loop, and it preserves atomicity: all tasks in the batch are enqueued together. Example: “Use sendEmailTask.batchTrigger(users.map(u => ({ payload: { userId: u.id } }))) to enqueue 500 welcome emails at once instead of looping and calling trigger() 500 times.”

delay A configuration option or method that postpones a task run by a specified duration. You can set a delay on a trigger() call (options.delay) to schedule the task to run in the future — useful for time-based workflows like trial expiration reminders. Example: “Pass { delay: '3d' } in the trigger options to schedule the follow-up email task to run three days after the initial signup — no cron job needed.”

Idempotency key A unique string passed in the trigger options to prevent duplicate task runs. If you trigger a task with the same idempotency key twice, Trigger.dev will return the result of the first run instead of enqueuing a second execution. Critical for preventing duplicate side effects in retry-heavy or at-least-once delivery systems. Example: “Pass idempotencyKey: \order-confirm-${order.id}“ when triggering the confirmation email task — if the checkout endpoint is called twice (double-submit), only one email will be sent.”

Retry policy The configuration that controls how Trigger.dev handles task failures. You can set the maximum number of retries, the delay between retries, and the backoff strategy (fixed, exponential). Retry policies are defined in the task() configuration. Example: “Set maxAttempts: 5 and factor: 2 in the retry configuration for the payment webhook task — exponential backoff reduces load on the payment provider during transient outages.”

Run dashboard The Trigger.dev web UI where you can monitor all task runs in real time — viewing their status (queued, executing, completed, failed), logs, payload, output, duration, and retry history. The dashboard is the primary tool for debugging failed runs. Example: “Open the run dashboard and filter by the process-refund task ID — you’ll see the exact error message and the input payload for the failing run.”

Attachments Files or data that can be associated with a task run in the Trigger.dev dashboard. You can attach metadata, output files, or structured data to a run using the context object (ctx.attachments), making them viewable in the dashboard alongside the run logs. Example: “Attach the generated PDF report to the task run using ctx.store.uploadFile() — the file will appear in the run dashboard so the team can download and verify the output without accessing the production database.”

How to Use This Vocabulary

Trigger.dev discussions tend to focus on three concerns: task design (what logic goes in run, what payload fields are needed), reliability (retry policy, idempotency keys), and observability (checking the run dashboard for failures, reading logs). Teams often debate payload design — passing IDs versus embedding full data — and idempotency key strategies to prevent duplicate side effects.

The run dashboard is a shared reference point for debugging. Engineers say “pull up the run in the dashboard” the same way they might say “check the logs” in other systems. Knowing how to navigate the dashboard — filtering by task ID, reading retry history, inspecting payloads — is part of day-to-day Trigger.dev work.

Example Conversation

Eli: Users are getting duplicate refund confirmation emails. The refund job is running twice. Kim: Check the run dashboard for the send-refund-email task — are there two runs with the same orderId in the payload? Eli: Yes, two runs fired within milliseconds of each other. Kim: Add an idempotency key using order-refund-${orderId} — that’ll deduplicate at the Trigger.dev level before the task even executes.

Practice

1. Define a Trigger.dev task for generating a monthly report: the task receives a userId and month parameter, generates a PDF, and emails it to the user. Name the task, describe its retry policy, and explain what idempotency key you would use and why.
2. Compare trigger() and batch() in terms of use case and efficiency. Write two sentences explaining when you would choose each, using the words “atomicity,” “loop,” and “throughput.”
3. Describe how you would use the run dashboard to debug a task that is failing on its third retry attempt. What information would you look for, and what would you check first?

Navigating the Flow: Practical Use of Trigger.dev Terminology

Let’s talk about how these Trigger.dev concepts actually play out in a typical engineering discussion. It’s not enough to just know what batch() or idempotency keys mean; we need to understand how they contribute to building reliable, scalable systems. Think of it like this: you could read the definition of “acceleration” in a physics textbook, but that doesn’t truly convey the feeling of speeding down a racetrack. Similarly, knowing the vocabulary is one thing, applying it during a code review or discussing a new feature with the team is quite another.

For example, imagine Sarah is reviewing your PR proposing a new worker to process image uploads. She comments: “This looks good, but can you ensure we’re using an idempotency key here? We want to avoid duplicate processing if the upload fails and retries.” This isn’t just about ticking a box; it’s about proactively addressing potential issues – ensuring that your code handles failures gracefully and doesn’t inadvertently double-process images. The discussion then moves beyond the technical term itself, into why it’s important in this specific context. We might discuss the implications of not using an idempotency key - potentially creating a backlog of unprocessed images or, worse, consuming excessive resources attempting to process the same image multiple times. It’s about building confidence that your system will behave predictably under various circumstances. This kind of conversation is crucial for ensuring the overall reliability and efficiency of our workflows.

Another common scenario involves discussing workload management with the Run dashboard team. You might find yourself saying, “I’m seeing a high number of delay requests in the last hour – it’s impacting response times.” This isn’t simply reporting a metric; it’s a direct request for understanding why this is happening and what steps can be taken to mitigate the impact. The team would then investigate, potentially identifying a bottleneck or needing to adjust the scheduling of tasks using batch() to distribute the load more effectively. The key here isn’t just knowing that delay represents a period of inactivity, but understanding how it relates to performance and system health, informing decisions about scaling and optimization.

Finally, consider a Slack message discussing the retry policy for a failed API call: “Hey team, we’re seeing intermittent failures with the external service – let’s implement a robust retry policy that includes exponential backoff.” This demonstrates how Trigger.dev terminology isn’t just isolated concepts; it’s integral to designing resilient systems capable of handling transient errors and maintaining functionality in challenging environments. It highlights the importance of proactive planning and architectural choices, directly influencing the stability of our applications.

// Example CLI command for managing batch processing (Hypothetical tool)
`batch -n 10 -i /path/to/data.json --process-function my_processing_function`