The @trigger.dev/sdk package is the primary developer-facing API for defining and triggering background tasks in the Trigger.dev system. It provides TypeScript functions and utilities for creating typed tasks, triggering execution, managing scheduling, and integrating with the task execution platform.
This document covers the SDK package structure, its main exports, and how it integrates with other system components. For detailed information about specific SDK capabilities, see:
The SDK is published as @trigger.dev/sdk on npm and provides multiple entry points for different use cases.
Sources: packages/trigger-sdk/package.json24-40
The package exports two main namespaces:
. / ./v3): Core task execution API including task definition, triggering, lifecycle hooks, and utilities./ai): Integration helpers for AI SDK tools and schema-based task creationThe SDK uses tshy for dual CommonJS/ESM builds with conditional source dialects. The build outputs both module formats to support various runtime environments.
| Export Path | Source File | Purpose |
|---|---|---|
. / ./v3 | src/v3/index.ts | Main SDK API |
./ai | src/v3/ai.ts | AI SDK integration |
Sources: packages/trigger-sdk/package.json18-42 packages/trigger-sdk/package.json92-131
Sources: packages/trigger-sdk/package.json52-64 packages/trigger-sdk/package.json80-88
@trigger.dev/core: Provides shared schemas, type definitions, serialization utilities, and error classes used across the SDK and platform@opentelemetry/api (v1.9.0): OpenTelemetry API for distributed tracing and context propagation@opentelemetry/semantic-conventions (v1.36.0): Standard semantic conventions for telemetry attributeszod: Required peer dependency for schema validation and type inferenceai: Optional peer dependency for Vercel AI SDK integration via ai.tool()The SDK requires Node.js ≥18.20.0 and is compatible with both CommonJS and ESM module systems.
Sources: packages/trigger-sdk/package.json89-91
Sources: packages/trigger-sdk/src/v3/index.ts (exported symbols), packages/core/CHANGELOG.md1-256 (architecture evolution)
The SDK operates in two distinct modes:
Task Definition Mode: Developer code imports SDK functions to define tasks with typed payloads, lifecycle hooks, and configuration. The CLI indexes these definitions during deployment.
Task Execution Mode: Worker processes import and execute task modules, providing runtime APIs (context, wait, metadata, logger) via the TaskExecutor class.
The current major version is 4.x, representing the "v3" execution engine architecture (confusingly named due to historical reasons). Key version milestones:
| Version | Release Date | Key Changes |
|---|---|---|
| 4.0.0 | 2024 | Run Engine 2.0, new lifecycle hooks, realtime streams v2 |
| 4.1.0 | 2024 | onStartAttempt hook, deprecated onStart |
| 4.2.0 | 2024 | Improved schema task exports (TS2742 fix) |
| 4.3.0 | 2024 | Debounce options, idempotency reset |
| 4.3.2 | Current | Batch trigger error improvements |
Sources: packages/trigger-sdk/CHANGELOG.md1-50
idempotencyKey from triggerAndWait and batchTriggerAndWait (prevents frozen runs)triggerAndPoll (never recommended)onStart lifecycle hook in favor of onStartAttemptreleaseConcurrencyOnWaitpoint option (replaced with automatic checkpoint behavior)Sources: packages/trigger-sdk/CHANGELOG.md269-314
The SDK provides type definitions via tshy dual builds. Both .d.ts files are generated for CommonJS and ESM consumers:
dist/commonjs/v3/index.d.tsdist/esm/v3/index.d.tsSources: packages/trigger-sdk/package.json33-41
The SDK respects the following environment variables during execution:
TRIGGER_API_URL: Override default API endpointTRIGGER_SECRET_KEY: Authentication token for triggering tasksOTEL_RESOURCE_ATTRIBUTES: Custom OpenTelemetry resource attributesSources: packages/core/CHANGELOG.md76-77 (runtime agnostic config)
Sources: packages/trigger-sdk/CHANGELOG.md152-247 (v4 execution flow), packages/core/CHANGELOG.md73-95 (trace correlation)
The SDK uses a custom HTTP client wrapper (zodfetch) that:
Sources: packages/core/CHANGELOG.md94 (suppress external instrumentation)
The SDK integrates deeply with OpenTelemetry to provide distributed tracing and structured logging:
Sources: packages/trigger-sdk/CHANGELOG.md161-247 (external trace correlation)
The v4 release updated OpenTelemetry dependencies to align with the latest stable API:
| Package | Previous | Current |
|---|---|---|
@opentelemetry/api | 1.9.0 | 1.9.0 (stable) |
@opentelemetry/api-logs | 0.52.1 | 0.203.0 |
@opentelemetry/core | - | 2.0.1 (new) |
@opentelemetry/semantic-conventions | 1.25.1 | 1.36.0 |
Sources: packages/trigger-sdk/CHANGELOG.md163-178
Tasks can propagate trace context to external systems using otel.withExternalTrace():
Sources: packages/trigger-sdk/CHANGELOG.md216-247 (external trace propagation example)
The following table summarizes major exports from the SDK for quick reference:
| Export | Type | Purpose | Child Page |
|---|---|---|---|
task() | Function | Define a task with typed payload and run function | 3.1 |
tasks | Namespace | Global task triggering API (trigger, batchTrigger) | 3.2 |
wait | Namespace | Wait utilities (for, until, createToken) | 3.2 |
metadata | Namespace | Run metadata API (set, get, current) | 3.2 |
logger | Object | Structured logging (info, warn, error) | 3.4 |
runs | Namespace | Run management (retrieve, list, cancel) | 3.2 |
schedules | Namespace | Scheduled task registration | 3.2 |
batch | Namespace | Batch triggering (trigger, triggerByTask) | 3.2 |
defineConfig() | Function | Project configuration (used by CLI) | 3.3 |
ai.tool() | Function | Create AI SDK tool from schema task | 3.1 |
Sources: packages/trigger-sdk/src/v3/index.ts (exports)
During development, the CLI builds worker code with esbuild in watch mode and maintains a WebSocket connection to the platform. Task code is hot-reloaded on file changes.
Sources: packages/cli-v3/CHANGELOG.md175-226 (dev command improvements)
The SDK uses tshy for building dual-format packages:
src/v3/dist/commonjs/, ESM in dist/esm/@triggerdotdev/source dialect for conditional compilationSources: packages/trigger-sdk/package.json18-31
The SDK depends on and coordinates with several other packages in the monorepo:
| Package | Relationship | Purpose |
|---|---|---|
@trigger.dev/core | Dependency | Shared schemas, types, serialization utilities |
trigger.dev (CLI) | Consumer | Imports SDK for task indexing and execution |
@trigger.dev/build | Used by CLI | Build extensions for Prisma, Python, etc. |
@trigger.dev/react-hooks | Sibling | React hooks for realtime run monitoring |
@trigger.dev/rsc | Sibling | React Server Components integration |
Sources: packages/trigger-sdk/package.json52-64 packages/cli-v3/package.json83-98
Key changes developers need to address:
onStart with onStartAttempt and check ctx.run.attempt.number === 1 if first-attempt-only logic is neededidempotencyKey from any triggerAndWait or batchTriggerAndWait callsDEQUEUED, WAITING instead of FROZEN)releaseConcurrency options (now automatic)Sources: packages/trigger-sdk/CHANGELOG.md56-92 (v4.1.0 lifecycle changes), packages/trigger-sdk/CHANGELOG.md269-311 (v4.0.0 breaking changes)
Sources: packages/trigger-sdk/package.json1-131 packages/trigger-sdk/CHANGELOG.md1-323 packages/core/package.json1-581 packages/core/CHANGELOG.md1-256 packages/cli-v3/package.json1-162 packages/build/package.json1-215
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.