Trigger.dev

Home

v3 Developer Preview

Integrations

Reference

Examples

Community

Get run

Welcome to the Trigger.dev v3 documentation.

Introduction

How to get started in 3 minutes using the CLI and SDK.

Quick start

How to upgrade v2 jobs to v3 tasks, and how to use them together.

Upgrading from v2

Changelog

What features are currently available in the Developer Preview

Feature matrix

Please let us know if you encounter an issue not on this list.

Known issues

Limits & Performance

Your tasks live inside /trigger folders. Code in these is bundled and deployed together.

/trigger folders

Tasks are functions that can run for a long time and provide strong resilience to failure.

Tasks

Tasks: Overview

Triggering

How to authenticate with Trigger.dev so you can trigger tasks.

API keys

The simplest type of task which can be triggered from elsewhere in your code.

Regular tasks

A task that is triggered on a recurring schedule using CRON syntax or an interval.

Scheduled tasks

You can use Zod to define a catalog of events and then attach those events to your tasks.

Zod tasks

A task that is triggered when a webhook is received from an API.

Webhook tasks

This file is used to configure your project and how it's bundled.

trigger.config file

The trigger.config.ts file

The `trigger.dev dev` command is used to run your tasks locally.

CLI dev command

You can use the dashboard to run a test of your tasks.

Run tests

Any environment variables used in your tasks need to be added so the deployed code will run successfully.

Environment Variables

The `trigger.dev deploy` command can be used to manually deploy.

CLI deploy command

You can easily deploy your tasks with GitHub actions.

GitHub Actions

When you deploy to Vercel, automatically deploy your associated tasks.

Vercel integration

Tasks are the core of Trigger.dev. They are long-running processes that are triggered by events.

Writing tasks: Introduction

How to use the built-in logging and tracing system.

Logging and tracing

How to deal with errors and write reliable tasks.

Errors & Retrying

During your run you can wait for a period of time or for something to happen.

Overview

Wait: Overview

Wait for a period of time, then continue execution.

Wait for

Wait until a date, then continue execution.

Wait until

Wait until an event has been received, then continue execution.

Wait for event

Wait until a `Request` has been received at the provided URL, then continue execution.

Wait for request

Configure what you want to happen when there is more than one run at a time.

Concurrency & Queues

We use atomic versioning to ensure that started tasks are not affected by changes to the task code.

Versioning

Configure the number of vCPUs and GBs of RAM you want the task to use.

Machines

An API call or operation is “idempotent” if it has the same result when called more than once.

Idempotency

You can reattempt a task that has failed all of its attempts. You can also replay a task with a new version of your code.

Reattempting & Replaying

You can add filters to your tasks so they're only triggered when certain conditions are met.

Trigger filters

Send and receive notifications from your tasks to make your other systems aware of changes. For example, you can live-update your website as a task progresses.

Notifications

You can rollback changes when errors happen, to give transactional guarantees to your operations.

Rollbacks

You can use any Node.js library inside the run function, or do HTTP requests.

Using APIs

This function is called before the `run` function, it allows you to wrap the run function with custom code.

Middleware

Automated tests

The dashboard has many features including: managing your projects, viewing run logs, editing environment variables and more.

Dashboard: overview

Find runs and view the detailed traces and logs for each run.

Runs

Dashboard: runs

Test your tasks in Dev, Staging and Prod from the dashboard.

Tests

Dashboard: tests

Add, edit and delete Environment Variables from the Dashboard.

Dashboard: environment variables

The task() function is the simplest way to create a long-running task.

task()

Trigger a task on a recurring schedule using a CRON expression.

cron.task()

Trigger a task with many different CRON schedules. For example you can use this to let your users select when they want a reminder.

cron.dynamic()

Trigger a task on a recurring schedule using the time interval you want between runs.

interval.task()

Trigger a task with many different interval schedules. For example you can use this to let your users select how often they want a reminder.

interval.dynamic()

A task where the payload is parsed using a zod schema.

zod.task()

Create a set of events with names and payloads that are parsed using Zod schemas.

zod.catalog()

task.trigger()

Trigger a task from inside another task, and wait for the result.

task.triggerAndWait()

Trigger a task many times at once from your code.

task.batchTrigger()

Trigger a task many times at once from inside another task, and wait for all the results.

task.batchTriggerAndWait()

Inside a task, wait for a period of time before continuing.

wait.for()

Inside a task, wait until the specified date before continuing.

wait.until()

Inside a task, wait until a specific event is received before continuing.

wait.forEvent()

Inside a task, wait until a specific request is received before continuing.

wait.forRequest()

Inside a task, retry the wrapped code if it throws an error.

retry.onThrow()

Inside a task, do a fetch request that will retry (you can specify the retry conditions).

retry.fetch()

Useful when writing automated tests – it will intercept matching HTTP requests and respond with what you provide.

retry.interceptFetch()

Create a set of events that can be emitted from your tasks. These can be subscribed to from your application to provide real-time updates to your users.

notification.catalog()

Send a notification from your tasks. These can be subscribed to from your application to provide real-time updates to your users.

notify()

Create queue settings that can be used when triggering a task.

queue()

The Context object is part of the `run` function parameter and provides information about the current run.

Context

init

trigger.dev init

trigger.dev dev

deploy

trigger.dev deploy

This command will log you in to the CLI. Required to run any other command.

login

trigger.dev login

This command will log you out of the CLI.

logout

trigger.dev logout

This command can be used to update all of your trigger.dev packages to the latest versions.

update

trigger.dev update

build

trigger.dev build

This command will return information about you, the logged in user.

whoami

trigger.dev whoami

Start a run using the Task id, payload and options.

Start run

Get runs

Creates a new run with the same payload and options as the original run.

Replay run

Cancel run

List Schedules

Create a new schedule based on the specified options.

Create Schedule

Retrieve Schedule

Update Schedule

Delete Schedule

Deactivate Schedule

Activate Schedule

An overview of how Trigger.dev v3 works under the hood.

How it works

Architecture: How it works

We built a reliable and fair multi-tenant queue that controls triggering all tasks.

Getting Started

Fundamentals

Development

Deployment

Writing tasks

Dashboard

API reference

Architecture

Open source

Help

Get run