Trigger.dev is a background jobs framework that enables developers to define, schedule, and execute long-running asynchronous tasks with built-in observability, checkpointing, and queue management. The system consists of an SDK for task definitions, a CLI for local development and deployment, a Remix web application for monitoring and management, and a distributed execution engine for running tasks in containerized workers.
This page provides an architectural overview of the Trigger.dev repository structure, its major subsystems, and how they interact. For detailed information about specific components, refer to the specialized wiki pages: Monorepo Structure, Trigger.dev SDK, Task Execution Engine, Web Application, and Deployment Pipeline.
The Trigger.dev repository is organized as a pnpm monorepo containing:
@trigger.dev/sdk), CLI (trigger.dev), and supporting libraries for task definition and executionThe codebase supports both cloud-hosted and self-hosted deployments, with v3 and v4 execution runtime architectures running in parallel.
Sources: pnpm-lock.yaml1-50 package.json1-121
The framework exposes three primary packages to developers:
| Package | Purpose | Entry Points |
|---|---|---|
@trigger.dev/sdk | Task definition API, triggering, scheduling | packages/trigger-sdk/package.json24-28 |
trigger.dev (CLI) | Local dev server, deployment commands | packages/cli-v3/package.json46-49 |
@trigger.dev/core | Shared types, schemas, utilities | packages/core/package.json22-56 |
Task Definition Flow:
Sources: packages/trigger-sdk/package.json1-131 packages/cli-v3/package.json1-162 packages/core/package.json1-75
The webapp is a Remix application providing API endpoints, dashboard UI, and coordination logic:
Key Server Components:
The webapp handles:
POST /api/v1/tasks/index routesTriggerTaskService apps/webapp/app/v3/services/triggerTask.server.tsInitializeDeployment and image building workflowsSources: apps/webapp/app/root.tsx1-138 apps/webapp/app/entry.server.tsx1-180 apps/webapp/package.json1-301
The run engine orchestrates task execution across containerized workers:
Key Execution States:
PENDING → Task created, awaiting version infoQUEUED → In queue, waiting for workerEXECUTING → Worker running task codeWAITING → Suspended at checkpoint/waitpointCOMPLETED / FAILED / CANCELED → Terminal statesSources: apps/webapp/app/env.server.ts572-600 internal-packages/database/prisma/schema.prisma1-50
The repository follows strict layering with workspace dependencies:
Package Management:
tshy for dual ESM/CJS exports in published packagesSources: pnpm-lock.yaml1-50 package.json1-121 turbo.json1-120
The database schema defines the core domain model:
Multi-Tenancy Hierarchy: User → Organization → Project → RuntimeEnvironment
Task Versioning: BackgroundWorker represents a deployed code version with a contentHash. Each BackgroundWorkerTask within a worker corresponds to a task() export.
Execution Tracking: TaskRun holds the primary state, with TaskRunAttempt tracking retries, and TaskRunCheckpoint/TaskRunWaitpoint enabling pause/resume.
Sources: internal-packages/database/prisma/schema.prisma1-50 internal-packages/database/prisma/schema.prisma188-400
A typical task execution flow showing code integration points:
Key Code Paths:
Sources: packages/trigger-sdk/CHANGELOG.md224-398 packages/core/CHANGELOG.md104-149
Sources: pnpm-lock.yaml1-100 apps/webapp/package.json1-301 packages/trigger-sdk/package.json52-91
The system requires extensive configuration via environment variables defined in apps/webapp/app/env.server.ts1-600:
Database:
DATABASE_URL - PostgreSQL connection string with poolingDIRECT_URL - Direct database connection for migrationsDATABASE_CONNECTION_LIMIT - Connection pool size (default: 10)Redis Instances:
REDIS_HOST, REDIS_PORT - Main Redis for legacy MarQSRATE_LIMIT_REDIS_* - Dedicated instance for API rate limitingCACHE_REDIS_* - Application caching layerREALTIME_STREAMS_REDIS_* - Real-time subscription statePUBSUB_REDIS_* - Socket.IO adapter for multi-instance syncExecution Engine:
DEFAULT_ENV_EXECUTION_CONCURRENCY_LIMIT - Environment-wide concurrency (default: 100)RUN_ENGINE_WORKER_COUNT - Number of run engine worker processes (default: 4)MARQS_VISIBILITY_TIMEOUT_MS - Queue message visibility timeout (default: 15 minutes)Observability:
INTERNAL_OTEL_TRACE_EXPORTER_URL - OpenTelemetry collector endpointINTERNAL_OTEL_TRACE_SAMPLING_RATE - Trace sampling (default: 1/20 = 5%)DEV_OTEL_EXPORTER_OTLP_ENDPOINT - User's external OTLP endpointDeployment:
DEPLOY_REGISTRY_HOST - Container registry hostnameDEPLOY_REGISTRY_NAMESPACE - Image namespace (default: "trigger")DEPOT_TOKEN - Depot API token for remote buildsSources: apps/webapp/app/env.server.ts49-600
The CLI communicates with the webapp through authenticated HTTP and WebSocket connections:
Key CLI Commands:
trigger dev - Local development server with file watchingtrigger deploy - Build and push container image, create deploymenttrigger whoami - Display authenticated user/project infoSources: packages/cli-v3/package.json72-82 packages/cli-v3/CHANGELOG.md1-50
During task execution, the SDK communicates with the supervisor/coordinator:
Message Protocol: WebSocket-based with typed messages defined in @trigger.dev/core/v3/zodSocket
Key Message Types:
TASK_RUN_EXECUTION - Initial run contextTASK_RUN_COMPLETED - Successful completionTASK_HEARTBEAT - Liveness signalCHECKPOINT_CREATE - Request pauseWAIT_FOR_DURATION - Sleep until timeWAIT_FOR_TASK - Wait for child runThe supervisor manages the worker process lifecycle, checkpointing state to PostgreSQL for resumption.
Sources: packages/core/package.json44-56 packages/trigger-sdk/CHANGELOG.md224-270
The codebase contains both v3 and v4 execution architectures:
v3 (Legacy):
v4 (Current):
Active Code Paths:
The system determines runtime version based on BackgroundWorker.version field. Both versions use the same database schema and webapp infrastructure.
Sources: apps/webapp/app/env.server.ts288-292 packages/core/CHANGELOG.md107-144
Refresh this wiki
