SOP-001: Trigger.dev Project Setup

Fresh

Document ID: SOP-001 Version: 1.0 Status: Active Last Updated: 2026-02-21

Overview

This SOP covers initializing a new Trigger.dev project, configuring the SDK, and verifying local development is working.

Prerequisites

• Node.js 18+ or Bun installed
• Existing application project (Next.js, Node.js, Remix, etc.)
• Trigger.dev account at cloud.trigger.dev

Procedure Flow

Step-by-Step Procedure

Step 1: Create Your Account

1. Navigate to cloud.trigger.dev
2. Sign up with GitHub, Google, or email
3. Complete the onboarding: create an Organization and a Project
4. Note your Project Reference (shown in dashboard settings)

Step 2: Initialize the Project

Run in your project root:

npx trigger.dev@latest init

When prompted:

• MCP Server: Install if you use Cursor, Claude, or another AI coding assistant
• Login: Authenticate via browser when prompted
• Project: Select the project you created in Step 1
• Trigger directory: Accept default /trigger or specify a custom path
• Example task: Choose "Hello World" to validate setup

Step 3: Verify Generated Files

After init, confirm these files exist:

your-project/
├── trigger.config.ts          ← Main config file
└── trigger/
    └── example.ts             ← Example "Hello World" task

The trigger.config.ts should look like:

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "proj_your_project_ref",
  runtime: "node",
  logLevel: "log",
  maxDuration: 300,
  retries: {
    enabledInDev: true,
    default: {
      maxAttempts: 3,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 10000,
      factor: 2,
      randomize: true,
    },
  },
  dirs: ["./trigger"],
});

Step 4: Start Development Server

npx trigger.dev@latest dev

Successful output looks like:

Trigger.dev (latest)
------------------------------------------------------
✓ Connected to Trigger.dev cloud
✓ Watching /trigger directory
✓ Registered tasks: hello-world

Dashboard: https://cloud.trigger.dev/projects/proj_xxx/test

Step 5: Run a Test

1. Open the Dashboard URL shown in terminal
2. Select the hello-world task
3. Click Run test (no payload needed for this task)
4. Observe the run status update live
5. Check your terminal — task output appears there too

Step 6: Set Environment Variables

For triggering tasks from your backend code, add to your .env:

TRIGGER_SECRET_KEY="tr_dev_your_key_here"

Get this from: Dashboard → API Keys → Development

Verification Checklist

• [ ] trigger.config.ts exists in project root
• [ ] /trigger directory created with example task
• [ ] npx trigger.dev@latest dev runs without errors
• [ ] Example task visible in dashboard
• [ ] Test run completes successfully
• [ ] TRIGGER_SECRET_KEY added to .env

Troubleshooting

CLI Login Issues

If CLI login fails, try:

npx trigger.dev@latest logout
npx trigger.dev@latest login

Package Version Mismatch

Run dev with update check enabled (default). When prompted to update @trigger.dev/* packages, accept — version mismatches cause failed deploys.

Project Reference Not Found

Double-check your project ref in trigger.config.ts matches the one in your dashboard. Project refs start with proj_.

See Also

• SOP-002: Writing Tasks
• Quick Reference: Commands