How to Run Background Jobs with Trigger.dev: A Step‑by‑Step Guide
Background jobs are essential for offloading time‑consuming tasks like sending emails, processing images, or syncing data. Trigger.dev is an open‑source framework that makes it dead simple to create, trigger, and monitor these jobs with TypeScript‑first APIs and built‑in retries. This guide walks you through your first background job in minutes.
First, set up a new project. Install the CLI and initialise your configuration:
npx @trigger.dev/cli@latest init
This creates a trigger.config.ts file. Run the development server with npx @trigger.dev/cli@latest dev – a local dashboard becomes available at http://localhost:3030.
1. Define a Background Job
Create a file jobs/send-welcome-email.ts. Use the job() function from Trigger.dev:
import { job } from "@trigger.dev/sdk";
export const sendWelcomeEmail = job({
id: "send-welcome-email",
run: async (payload: { email: string; name: string }) => {
// Your email sending logic here
console.log(`Sending welcome to ${payload.email}`);
}
});
The job receives a payload when triggered and runs asynchronously.
2. Trigger the Job from Your App
Export your job and use trigger from the Trigger.dev client:
import { sendWelcomeEmail } from "@/jobs/send-welcome-email";
await sendWelcomeEmail.trigger({ email: "user@example.com", name: "Alice" });
The job is queued immediately. Trigger.dev handles retries (5 times by default) and delays if needed.
3. Monitor and Debug
Open the dashboard at localhost:3030. You’ll see every run, its status (success/failed), duration, and logs. Failed jobs show the exact error – enabling quick fixes without digging through server logs.
Conclusion
Trigger.dev removes the boilerplate of managing queues, retries, and monitoring. With just a few lines of code you get reliable background job execution. Start using it today and focus on what matters – your business logic.