Skip to main content
This guide walks you through creating an account, initializing Trigger.dev in an existing project, writing a task, running it in development, and deploying it to production.
You need Node.js 18.20.0 or later and an existing TypeScript or JavaScript project (Next.js, Remix, Express, etc.).
1

Create a Trigger.dev account

Sign up at cloud.trigger.dev. The onboarding flow will guide you through creating your first organization and project.Once you have a project, you’ll have access to API keys for both dev and prod environments from the API keys page in the dashboard.
2

Initialize Trigger.dev in your project

Run the init command in the root of your project:
npx trigger.dev@latest init
The CLI will:
  • Ask you to log in (or create an account) if you’re not already authenticated
  • Ask which project to connect to
  • Install @trigger.dev/sdk as a dependency
  • Create a trigger.config.ts configuration file
  • Create a /trigger directory with a sample hello-world.ts task
Your trigger.config.ts will look like this:
import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<your-project-ref>",
  dirs: ["./trigger"],
});
3

Write your first task

Open (or create) a file inside the /trigger directory. Tasks are defined using the task function from @trigger.dev/sdk and must be exported.
import { task, logger } from "@trigger.dev/sdk";

export const processOrder = task({
  id: "process-order",
  // Retry up to 3 times with exponential backoff
  retry: {
    maxAttempts: 3,
    minTimeoutInMs: 1000,
    maxTimeoutInMs: 10000,
    factor: 2,
  },
  run: async (payload: { orderId: string; userId: string }) => {
    logger.info("Processing order", { orderId: payload.orderId });

    // Your logic here — no timeout restrictions
    const result = await fulfillOrder(payload.orderId);

    logger.info("Order fulfilled", { orderId: payload.orderId, result });

    return { success: true, orderId: payload.orderId };
  },
});
Every task needs a unique id string within your project. The id is used to reference the task when triggering it and appears in the dashboard.
4

Start the dev server

Run the dev command from your project root:
npx trigger.dev@latest dev
This starts a local worker that:
  • Connects to Trigger.dev Cloud (or your self-hosted instance)
  • Watches your /trigger directory for changes and hot-reloads
  • Runs tasks locally in your Node.js process
  • Shows live logs in the terminal
You’ll see output like:
Trigger.dev v4.4.3

✔ Connected to Trigger.dev Cloud
✔ Watching /trigger for changes

  Tasks:
  • process-order   trigger/order.ts
Leave this running while you develop and test.
5

Trigger a test run

With the dev server running, open the Trigger.dev dashboard and navigate to your project. You’ll see your process-order task listed.Click the task, then click Test to open the test panel. Enter a JSON payload matching your task’s input type:
{
  "orderId": "order_123",
  "userId": "user_456"
}
Click Run test. The run executes in your local dev server and you can watch the logs in both the dashboard and the terminal.Alternatively, trigger the task programmatically from your application:
import { tasks } from "@trigger.dev/sdk";
import type { processOrder } from "./trigger/order";
//     👆 type-only import

// In an API route, server action, or any server-side code:
const handle = await tasks.trigger<typeof processOrder>("process-order", {
  orderId: "order_123",
  userId: "user_456",
});

console.log(handle.id); // Run ID for tracking
Import your task as a type-only import (import type) to avoid bundling task code into your application server.
6

Deploy to production

When you’re ready to deploy, run:
npx trigger.dev@latest deploy
The CLI will:
  1. Build your task code with esbuild and bundle dependencies
  2. Package the result into a Docker image
  3. Push the image to Trigger.dev’s registry
  4. Register the new deployment — your tasks are live immediately
To deploy to the staging environment instead:
npx trigger.dev@latest deploy --env staging
Once deployed, trigger tasks using your production API key. See API keys in the dashboard for details.

​
Next steps

How it works

Understand the architecture, checkpointing, and run lifecycle.

Writing tasks

Learn all the options for defining tasks — queues, concurrency, middleware, and more.

Triggering tasks

Trigger tasks from your API routes, webhooks, cron jobs, or other tasks.

Guides & examples

Framework-specific guides for Next.js, Remix, and more, plus example projects.

Build docs developers (and LLMs) love

Get started for freeTalk to us