Skip to main content
There are different types of tasks including regular tasks and scheduled tasks.

​
Hello world task and how to trigger it

Here’s an incredibly simple task:
/trigger/hello-world.ts
import { task } from "@trigger.dev/sdk";

const helloWorld = task({
  //1. Use a unique id for each task
  id: "hello-world",
  //2. The run function is the main function of the task
  run: async (payload: { message: string }) => {
    //3. You can write code that runs for a long time here, there are no timeouts
    console.log(payload.message);
  },
});
You can trigger this in two ways:
  1. From the dashboard using the “Test” feature.
  2. Trigger it from your backend code. See the full triggering guide here.
Here’s how to trigger a single run from elsewhere in your code:
Your backend code
import { helloWorld } from "./trigger/hello-world";

async function triggerHelloWorld() {
  //This triggers the task and returns a handle
  const handle = await helloWorld.trigger({ message: "Hello world!" });

  //You can use the handle to check the status of the task, cancel and retry it.
  console.log("Task is running with handle", handle.id);
}
You can also trigger a task from another task, and wait for the result.

​
Defining a task

The task function takes an object with the following fields.

​
The id field

This is used to identify your task so it can be triggered, managed, and you can view runs in the dashboard. This must be unique in your project – we recommend making it descriptive and unique.

​
The run function

Your custom code inside run() will be executed when your task is triggered. It’s an async function that has two arguments:
  1. The run payload - the data that you pass to the task when you trigger it.
  2. An object with ctx about the run (Context), and any output from the optional init function that runs before every run attempt.
Anything you return from the run function will be the result of the task. Data you return must be JSON serializable: strings, numbers, booleans, arrays, objects, and null.

​
retry options

A task is retried if an error is thrown, by default we retry 3 times. You can set the number of retries and the delay between retries in the retry field:
/trigger/retry.ts
export const taskWithRetries = task({
  id: "task-with-retries",
  retry: {
    maxAttempts: 10,
    factor: 1.8,
    minTimeoutInMs: 500,
    maxTimeoutInMs: 30_000,
    randomize: false,
  },
  run: async (payload: any, { ctx }) => {
    //...
  },
});
For more information read the retrying guide. It’s also worth mentioning that you can retry a block of code inside your tasks as well.

​
queue options

Queues allow you to control the concurrency of your tasks. This allows you to have one-at-a-time execution and parallel executions. There are also more advanced techniques like having different concurrencies for different sets of your users. For more information read the concurrency & queues guide.
/trigger/one-at-a-time.ts
export const oneAtATime = task({
  id: "one-at-a-time",
  queue: {
    concurrencyLimit: 1,
  },
  run: async (payload: any, { ctx }) => {
    //...
  },
});

​
machine options

Some tasks require more vCPUs or GBs of RAM. You can specify these requirements in the machine field. For more information read the machines guide.
/trigger/heavy-task.ts
export const heavyTask = task({
  id: "heavy-task",
  machine: {
    preset: "large-1x", // 4 vCPU, 8 GB RAM
  },
  run: async (payload: any, { ctx }) => {
    //...
  },
});

​
maxDuration option

By default tasks can execute indefinitely, which can be great! But you also might want to set a maxDuration to prevent a task from running too long. You can set the maxDuration on a task, and all runs of that task will be stopped if they exceed the duration.
/trigger/long-task.ts
export const longTask = task({
  id: "long-task",
  maxDuration: 300, // 300 seconds or 5 minutes
  run: async (payload: any, { ctx }) => {
    //...
  },
});
See our maxDuration guide for more information.

​
Global lifecycle hooks

When specifying global lifecycle hooks, we recommend using the init.ts file.
You can register global lifecycle hooks that are executed for all runs, regardless of the task. While you can still define these in the trigger.config.ts file, you can also register them anywhere in your codebase: 
import { tasks } from "@trigger.dev/sdk";

tasks.onStart(({ ctx, payload, task }) => {
  console.log("Run started", ctx.run);
});

tasks.onSuccess(({ ctx, output }) => {
  console.log("Run finished", ctx.run);
});

tasks.onFailure(({ ctx, error }) => {
  console.log("Run failed", ctx.run);
});

​
init.ts

If you create a init.ts file at the root of your trigger directory, it will be automatically loaded when a task is executed. This is useful if you want to register global lifecycle hooks, or initialize a database connection, etc.
init.ts
import { tasks } from "@trigger.dev/sdk";

tasks.onStart(({ ctx, payload, task }) => {
  console.log("Run started", ctx.run);
});

​
Lifecycle functions