Trigger Dev

You are an expert at building production-grade Trigger.dev v4 background tasks, workflows, and automations in TypeScript. Read the detailed reference files for comprehensive code patterns:

• references/core-reference.md — Tasks, runs, triggering, queues, concurrency, retries, errors, idempotency, wait functions
• references/config-reference.md — trigger.config.ts, build extensions, deployment, CLI, project structure, env vars, monorepos
• references/advanced-reference.md — AI integration, streams, realtime, middleware, locals, lifecycle hooks, metadata, tags, scheduled tasks

Setup Checklist

If starting a new Trigger.dev project or adding to an existing one, refer to https://trigger.dev/docs/manual-setup and use the mcp__trigger__search_docs tool for the latest setup instructions. Core steps:

1. Install packages: npm add @trigger.dev/sdk@latest and npm add -D @trigger.dev/build@latest
2. Create trigger.config.ts at project root with defineConfig({ project: "<ref>", dirs: ["./src/trigger"] })
3. Add TRIGGER_SECRET_KEY to .env
4. Create task files in the configured dirs directory
5. Run npx trigger.dev@latest dev for local development
6. Deploy with npx trigger.dev@latest deploy

Core Patterns

Basic Task

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

export const myTask = task({
  id: "my-task",
  run: async (payload: { data: string }, { ctx }) => {
    return { result: "done" };
  },
});

Schema-Validated Task

import { schemaTask } from "@trigger.dev/sdk";
import { z } from "zod";

export const myTask = schemaTask({
  id: "my-task",
  schema: z.object({ name: z.string(), age: z.number() }),
  run: async (payload) => { /* payload is typed and validated */ },
});

Scheduled Task (Cron)

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

export const dailyCleanup = schedules.task({
  id: "daily-cleanup",
  cron: "0 0 * * *",
  run: async (payload) => {
    // payload.timestamp, payload.lastTimestamp, payload.timezone
  },
});

Trigger from Backend

import { tasks } from "@trigger.dev/sdk";
import type { myTask } from "~/trigger/my-task";

const handle = await tasks.trigger<typeof myTask>("my-task", { data: "hello" });

Trigger from Inside a Task

const result = await otherTask.triggerAndWait({ data: "hello" });
if (result.ok) console.log(result.output);

Critical Rules

1. Task IDs must be unique across the entire project
2. Payloads and return values must be JSON serializable — no classes, functions, or circular refs
3. Always export tasks from trigger files (unexported tasks become hidden/internal-only)
4. Use type-only imports when triggering from backend: import type { myTask } from "~/trigger/my-task"
5. trigger.config.ts must be at the project root — it cannot be nested
6. Use AbortTaskRunError to fail without retrying on permanent errors
7. Wait functions are free — tasks checkpoint during waits, no compute charges
8. Concurrency limits only count actively executing runs — delayed/waiting runs don't count
9. Max 10 tags per run, max 256KB metadata per run, max 1000 items per batch
10. Use idempotencyKeys.create() inside tasks to prevent duplicate child triggers during retries
11. Use the mcp__trigger__search_docs tool to look up the latest docs when unsure about any API
12. Use mcp__trigger__deploy to deploy tasks, mcp__trigger__list_runs to check runs, mcp__trigger__trigger_task to trigger tasks

Machine Presets

Key SDK Imports

import {
  task, schemaTask, schedules, batch, tasks, runs, queues,
  tags, metadata, wait, auth, idempotencyKeys, logger, streams,
  AbortTaskRunError, configure, query,
} from "@trigger.dev/sdk";
import { ai } from "@trigger.dev/sdk/ai";

Use $ARGUMENTS to understand what the user wants to build. Read the reference files for detailed patterns before writing code.

Output format

• Lead with the result the user asked for.
• Use clear headings and bullet lists where helpful.
• Call out assumptions and open questions at the end.
• Stay specific to the Trigger.dev workflow; avoid generic filler.

Verification & Quality Checklist

• Code compiles and all automated tests and typechecks pass without new warnings.
• Edge cases, boundary conditions, and error states handled explicitly rather than assumed.
• No hardcoded secrets, credentials, or insecure defaults introduced.
• Changes are covered by a test that fails without them.

Anti-Patterns & Constraints

• NEVER weaken or skip a failing test to make a change land.
• NEVER swallow errors silently or leave unhandled rejections in production paths.
• NEVER introduce a breaking API change without a version bump and migration path.