@trigger.dev/sdk

@trigger.dev/sdk is the official TypeScript/JavaScript client for Trigger.dev, an open-source platform for building and deploying fully-managed background jobs, workflows, and AI agents. It lets you define long-running tasks as plain async TypeScript functions — no special DSL — and get automatic retries, managed queues, elastic scaling, and full observability without operating your own worker infrastructure.

Beyond simple background jobs, the SDK covers scheduling, batch triggering, idempotency keys, run metadata, and first-class primitives for AI agent workloads (prompt management, chat sessions, auto-instrumented telemetry), making it equally suited to a nightly ETL job or a multi-step autonomous agent that runs for hours.

What You Get

• Task definition and triggering API (task(), trigger(), batchTrigger()) for background jobs written in plain TypeScript
• Scheduling primitives for cron-style and interval-based recurring tasks
• Idempotency key support to safely retry or dedupe task invocations
• Run metadata, heartbeats, and caching helpers for long-running or resumable tasks
• AI-specific primitives: prompt management, chat sessions, and auto-instrumented telemetry for agent workloads
• A companion CLI (in the same monorepo) for local dev, login, init, and deploy

Common Use Cases

• Offloading long-running or resource-heavy work (video processing, PDF generation, large imports) from a web request into a managed background task
• Building multi-step, hours-long AI agent workflows with retries and observability out of the box
• Scheduling recurring jobs (nightly syncs, digest emails) without maintaining your own cron infrastructure
• Coordinating batch and fan-out/fan-in task execution with idempotency guarantees

Under The Hood

Architecture - The SDK (packages/trigger-sdk/src/v3) exposes a task-definition layer that compiles to metadata Trigger.dev’s control plane understands, alongside dedicated modules for batching (batch.ts), scheduling, idempotency keys (idempotencyKeys.ts), run metadata (metadata.ts), and AI-specific concerns like prompt management (prompts.ts) and chat sessions (chat-server.ts, chat-client.ts) — the latter split into server/client/tab-coordinator files to support multi-tab browser sessions. It’s one of ~9 packages in the triggerdotdev/trigger.dev monorepo (cli-v3, core, plugins, redis-worker, rsc, schema-to-json, python, react-hooks), with the SDK as the most-installed entry point (over 620k weekly downloads vs. ~364k for the trigger.dev CLI package).

Tech Stack - TypeScript throughout, built with tshy for dual ESM/CJS output, OpenTelemetry-based auto-instrumentation (aiAutoTelemetry.ts, otel.ts) for tracing task and AI agent execution, and a companion @trigger.dev/core package for shared types/utilities across the CLI, SDK, and platform.

Code Quality - The package includes 26+ dedicated test files (chat-server.test.ts, chat-tab-coordinator.test.ts, createStartSessionAction.test.ts, among others) covering the chat/session coordination logic specifically, reflecting the complexity of managing multi-tab AI chat state; the wider monorepo also runs Playwright end-to-end tests (playwright.config.ts) and uses oxlint custom plugins for repo-specific lint rules.

API Design - The core mental model is deliberately minimal — define a task as an async function, call trigger() or batchTrigger() to run it — while advanced capabilities (scheduling, idempotency, metadata, AI telemetry) are layered on as opt-in imports (@trigger.dev/sdk/ai, individual modules) rather than baked into the base API, keeping the on-ramp shallow for simple background-job use cases.