The Trigger.dev SDK comprises a collection of TypeScript packages that enable developers to define, develop, test, and deploy background tasks. This document provides an overview of the SDK package architecture, the main packages and their roles, and how they integrate with each other.
For detailed information about specific SDK features, see:
The SDK is organized as a monorepo with multiple published packages, each serving a distinct purpose in the task definition and execution pipeline.
Sources: packages/trigger-sdk/package.json1-131 packages/core/package.json1-583 packages/cli-v3/package.json1-162 packages/build/package.json1-215 packages/react-hooks/package.json1-75 packages/rsc/package.json1-75
| Package | NPM Name | Purpose | Main Exports |
|---|---|---|---|
| SDK | @trigger.dev/sdk | Task definition and triggering API | task, createTask, createSchemaTask, runs, wait, metadata |
| Core | @trigger.dev/core | Shared utilities, types, schemas | Types, schemas, OpenTelemetry utilities, serialization |
| CLI | trigger.dev | Development and deployment commands | trigger binary (init, dev, deploy, etc.) |
| Build | @trigger.dev/build | Build-time extensions | prismaExtension, playwrightExtension, etc. |
| React Hooks | @trigger.dev/react-hooks | Real-time run updates in React | useRealtimeRun, useRealtimeRunsWithTag |
| RSC | @trigger.dev/rsc | React Server Components support | RSC-compatible utilities |
Sources: packages/trigger-sdk/package.json23-29 packages/core/package.json22-56 packages/cli-v3/package.json32-34 packages/build/package.json23-35
@trigger.dev/sdk)The @trigger.dev/sdk package is the primary interface developers use to define and interact with tasks. It provides a TypeScript-first API with full type inference.
Sources: packages/trigger-sdk/package.json24-29 packages/trigger-sdk/CHANGELOG.md1-100
The SDK provides two main entry points:
@trigger.dev/sdk or @trigger.dev/sdk/v3): Core task definition and runtime APIs@trigger.dev/sdk/ai): AI SDK integration utilitiesSources: packages/trigger-sdk/package.json94-126
The SDK package has minimal required dependencies but supports optional peer dependencies:
| Dependency | Type | Version | Purpose |
|---|---|---|---|
@trigger.dev/core | Required | workspace:4.3.3 | Core utilities and types |
zod | Peer | ^3.0.0 || ^4.0.0 | Schema validation (required) |
ai | Peer (optional) | ^4.2.0 || ^5.0.0 || ^6.0.0 | Vercel AI SDK integration |
@opentelemetry/api | Required | 1.9.0 | OpenTelemetry tracing |
Sources: packages/trigger-sdk/package.json52-91
The SDK follows semantic versioning and maintains compatibility across the v4 release line. Recent versions include:
Sources: packages/trigger-sdk/CHANGELOG.md1-40
@trigger.dev/core)The @trigger.dev/core package provides the foundational utilities, types, and schemas shared across all Trigger.dev packages. It is not typically imported directly by user code but is a dependency of all other packages.
Sources: packages/core/package.json22-56 packages/core/package.json224-577
The core package is organized into several module categories, each exported through specific paths:
| Export Path | Purpose | Key Exports |
|---|---|---|
@trigger.dev/core | Main types and utilities | Common types, schemas, logger |
@trigger.dev/core/v3 | V3-specific APIs | Task context types, API client |
@trigger.dev/core/v3/schemas | Validation schemas | Zod schemas for payloads, options |
@trigger.dev/core/v3/otel | Observability | OpenTelemetry integrations |
@trigger.dev/core/v3/workers | Worker runtime | TaskRunContext, worker types |
@trigger.dev/core/v3/utils/* | Utility modules | durations, retries, serialization |
Sources: packages/core/package.json61-156
Core includes comprehensive OpenTelemetry support with recent major version updates (v4.0.0):
| Package | Version | Change |
|---|---|---|
@opentelemetry/api | 1.9.0 | Stable API (no change) |
@opentelemetry/api-logs | 0.203.0 | Major update from 0.52.1 |
@opentelemetry/sdk-trace-base | 2.0.1 | Major update from 1.25.1 |
@opentelemetry/sdk-logs | 0.203.0 | Major update from 0.52.1 |
@opentelemetry/semantic-conventions | 1.36.0 | Minor update from 1.25.1 |
Sources: packages/trigger-sdk/CHANGELOG.md177-191 packages/core/package.json170-186
Core provides a custom serialization layer that extends JSON to support:
Date objectsBuffer objectsBigInt valuesundefined valuesThis serialization is used for task payloads, outputs, and metadata throughout the system.
Sources: packages/core/package.json402-411 packages/core/CHANGELOG.md566
trigger.dev)The CLI package provides the trigger command-line tool for initializing projects, running local development servers, and deploying tasks to production.
Sources: packages/cli-v3/package.json32-34 packages/cli-v3/CHANGELOG.md189-260
The CLI is published as trigger.dev on npm and installs a trigger binary:
bin/trigger -> dist/esm/index.js
Sources: packages/cli-v3/package.json32-34
| Command | Purpose | Key Features |
|---|---|---|
trigger init | Initialize new project | Creates trigger/ directory, trigger.config.ts, installs dependencies |
trigger dev | Start dev server | Hot reload, live logs, connects to cloud platform |
trigger deploy | Deploy to production | Builds Docker image, pushes to registry, creates deployment |
trigger login | Authenticate CLI | Manages profiles, obtains access tokens |
trigger whoami | Display current profile | Shows project details, environment info |
trigger update | Update packages | Updates SDK packages to latest versions |
Sources: packages/cli-v3/CHANGELOG.md189-260
The CLI includes Model Context Protocol (MCP) server capabilities for AI assistant integration:
mcpName: "io.github.triggerdotdev/trigger.dev"
This enables AI assistants like Claude and Cursor to interact with Trigger.dev programmatically.
Sources: packages/cli-v3/package.json15 packages/cli-v3/CHANGELOG.md173
The CLI depends on several build-related packages:
| Dependency | Version | Purpose |
|---|---|---|
@trigger.dev/build | workspace:4.3.3 | Build extensions system |
@trigger.dev/core | workspace:4.3.3 | Core utilities |
esbuild | ^0.23.0 | JavaScript bundling |
@depot/cli | 0.0.1-cli.2.80.0 | Remote Docker builds |
chokidar | ^3.6.0 | File watching for dev mode |
Sources: packages/cli-v3/package.json83-149
@trigger.dev/build)The @trigger.dev/build package provides a plugin system for customizing the build process and adding deployment-time functionality.
Sources: packages/build/package.json23-35 packages/build/CHANGELOG.md1-50
Build extensions fall into several categories:
| Category | Extensions | Purpose |
|---|---|---|
| Database | prismaExtension | Prisma schema generation, migrations |
| Browser | playwrightExtension, puppeteerExtension, lightpandaExtension | Browser automation setup |
| Media | ffmpegExtension, audioWaveformExtension | Media processing tools |
| Environment | syncVercelEnvVars, syncNeonEnvVars | Environment variable synchronization |
| Core | coreExtension, typescriptExtension | Base functionality |
Sources: packages/build/package.json48-68
The prismaExtension supports three distinct modes for different Prisma versions and setups:
prisma-client-js providerprisma-client provider and engineType = "client"Sources: packages/build/CHANGELOG.md50-428
| Export Path | Purpose |
|---|---|
@trigger.dev/build | Main exports |
@trigger.dev/build/extensions | All extensions |
@trigger.dev/build/extensions/prisma | Prisma extension only |
@trigger.dev/build/extensions/playwright | Playwright extension only |
@trigger.dev/build/extensions/core | Core extension utilities |
Sources: packages/build/package.json99-210
Trigger.dev provides two packages for integrating task execution with frontend applications.
@trigger.dev/react-hooks)Sources: packages/react-hooks/package.json1-75 packages/react-hooks/CHANGELOG.md1-100
The React hooks package provides:
Sources: packages/react-hooks/CHANGELOG.md55-68 packages/react-hooks/package.json39-41
@trigger.dev/rsc)The @trigger.dev/rsc package enables React Server Component integration, allowing tasks to be triggered and monitored from server components without client-side JavaScript.
This package bundles React 19 RC internally to support the RSC protocol.
Sources: packages/rsc/package.json1-75 packages/rsc/package.json42-43
Sources: packages/trigger-sdk/package.json52-56 packages/core/package.json170-202 packages/cli-v3/package.json83-149 packages/build/package.json79-86 packages/react-hooks/package.json39-54 packages/rsc/package.json39-44
All packages in the SDK follow synchronized versioning, currently at v4.3.3. This ensures compatibility across the entire stack.
The monorepo uses workspace protocol (workspace:4.3.3) to ensure all internal dependencies remain in sync. When one package is released, all dependent packages are released together.
Sources: packages/trigger-sdk/package.json55 packages/cli-v3/package.json96-98
All packages are built with tshy, producing both CommonJS and ESM outputs:
dist/commonjs/ (Node.js require)dist/esm/ (ESM import)The packages support TypeScript's typesVersions for proper path mapping.
Sources: packages/trigger-sdk/package.json18-32 packages/core/package.json18-60
All packages require Node.js >= 18.20.0:
Sources: packages/trigger-sdk/package.json89-91 packages/core/package.json221-223
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.