Purpose: This document provides a high-level introduction to the Trigger.dev codebase, describing its purpose, core architectural patterns, main components, and repository organization. It serves as the entry point for understanding how Trigger.dev's distributed task execution system is structured and how its components interact.
Scope: This page covers the overall system architecture and component relationships. For detailed information about specific subsystems, see:
Trigger.dev is an open-source background jobs framework implemented as a TypeScript monorepo. It enables developers to define, schedule, and execute long-running tasks with features including retry logic, concurrency management, checkpointing, and real-time monitoring. The system follows a control plane / data plane architecture where the webapp orchestrates execution while workers run the actual task code.
The platform supports both local development (via trigger dev) and production deployments (via trigger deploy), with the same task code running in both environments. Tasks are defined using the @trigger.dev/sdk package, deployed as Docker containers, and executed in either Kubernetes or Docker environments managed by provider services.
Sources: apps/webapp/package.json1-298 packages/trigger-sdk/package.json1-131 packages/cli-v3/package.json1-162
Architecture: Control plane vs data plane separation with webapp (control) managing PostgreSQL state and Redis queues, while workers (data) execute task code in isolated containers. The RunEngine class mediates between the queue layer and worker processes using IPC communication.
Sources: internal-packages/run-engine/src/engine/index.ts1-300 apps/webapp/app/root.tsx1-133 apps/webapp/server.ts1-100
apps/webapp)The Remix-based web application serves as the central orchestrator, providing the dashboard UI, REST/GraphQL APIs, and coordination services. It manages deployments, stores task run state in PostgreSQL, and enqueues tasks to Redis for execution.
Key responsibilities:
TriggerTaskServiceTaskRun modelgraphile-workerSources: apps/webapp/package.json1-298 apps/webapp/app/entry.server.tsx1-100
internal-packages/run-engine)The RunEngine class orchestrates task execution through a system of coordinated subsystems:
| System | Purpose | Key Classes |
|---|---|---|
DequeueSystem | Retrieves tasks from Redis queues | DequeueSystem, FairQueueSelectionStrategy |
ExecutionSnapshotSystem | Tracks run state changes | ExecutionSnapshotSystem, TaskRunExecutionSnapshot |
RunAttemptSystem | Manages attempt lifecycle | RunAttemptSystem.startAttempt(), completeAttempt() |
WaitpointSystem | Handles blocking operations | WaitpointSystem.createWaitpoint(), completeWaitpoint() |
CheckpointSystem | Suspends/resumes runs | CheckpointSystem.createCheckpoint(), resumeCheckpoint() |
EnqueueSystem | Adds tasks to queues | EnqueueSystem.enqueue() |
BatchSystem | Coordinates batch operations | BatchSystem, BatchQueue |
Sources: internal-packages/run-engine/src/engine/index.ts76-300 internal-packages/run-engine/src/engine/types.ts1-100
packages/trigger-sdk)The @trigger.dev/sdk package provides the developer-facing API for defining and triggering tasks:
Core exports include:
task(): Creates task definitionstrigger(), batchTrigger(): Initiates task executionwait: Suspends execution (checkpoints)metadata: Stores run metadatalogger: Structured logging APISources: packages/trigger-sdk/package.json1-131 packages/trigger-sdk/CHANGELOG.md1-500
packages/cli-v3)The trigger.dev CLI provides commands for local development and deployment:
| Command | Purpose | Key Files |
|---|---|---|
trigger dev | Local development server | packages/cli-v3/src/commands/dev.ts |
trigger deploy | Build and deploy to production | packages/cli-v3/src/commands/deploy.ts |
trigger init | Initialize new project | packages/cli-v3/src/commands/init.ts |
trigger whoami | Show current profile | packages/cli-v3/src/commands/whoami.ts |
Sources: packages/cli-v3/package.json1-162 packages/cli-v3/CHANGELOG.md1-200
Provider applications manage task execution in different infrastructure environments:
apps/kubernetes-provider): Manages pods using @kubernetes/client-node, creates pods with labels for task identificationapps/docker-provider): Manages containers using dockerode, runs tasks in local Docker environmentsapps/supervisor): Multi-provider orchestrator that can manage both Kubernetes and Docker workloadsSources: apps/kubernetes-provider/package.json160-180 apps/docker-provider/package.json141-158 apps/supervisor/package.json182-207
Local Development: The trigger dev command creates a persistent WebSocket connection to the cloud platform, enabling hot-reload development. Task code runs locally in the developer's environment while state is managed by the cloud platform.
Deployment: The trigger deploy command uses esbuild to bundle task code, builds a Docker image (locally or via Depot), pushes to a container registry, and finalizes the deployment with the webapp. The webapp then coordinates with providers to pre-pull images and update routing.
Sources: packages/cli-v3/package.json72-81 packages/build/package.json1-98
Pipeline Stages:
TriggerTaskService validates payload, checks idempotency, creates TaskRun recordRunEngine selects queue using FairQueueSelectionStrategyTaskRunProcess.fork(), communicates via IPCSources: internal-packages/run-engine/src/engine/systems/dequeueSystem.ts1-100 internal-packages/run-engine/src/engine/systems/runAttemptSystem.ts1-100
Package Categories:
apps/*): Deployable services (webapp, coordinator, providers)packages/*): NPM packages for developers (SDK, CLI, React hooks)internal-packages/*): Shared infrastructure (database, run-engine, caching)Dependency Flow: @trigger.dev/core sits at the foundation, providing schemas and utilities. Internal packages build on core for infrastructure (database, redis, tracing). Public packages expose developer APIs. Applications consume everything.
Build System: Uses pnpm workspaces with turbo for parallel builds. TypeScript code compiled via tshy for dual ESM/CJS support. Monorepo managed via @manypkg/cli for version consistency.
Sources: package.json1-121 turbo.json1-100 pnpm-lock.yaml1-200
The system is configured through multiple mechanisms:
trigger.config.ts: Project configuration using defineConfig() from @trigger.dev/sdk/v3:
Environment Variables: The webapp reads configuration from env.server.ts which validates environment variables using Zod schemas, including database URLs, Redis configuration, deployment registry settings, OTEL configuration, and rate limiting parameters.
Runtime Detection: The system detects Node.js, Bun, and other runtimes at startup to configure appropriate execution environments.
Sources: apps/webapp/app/env.server.ts1-600 packages/core/package.json22-56
Telemetry Stack: Uses OpenTelemetry for distributed tracing with configurable exporters. Logs and spans are correlated with trace IDs. The system supports both internal observability (stored in ClickHouse) and external exporters (Datadog, Honeycomb, etc.).
Metrics: Prometheus metrics exposed via prom-client for monitoring queue depths, execution times, concurrency levels, and error rates.
Sources: apps/webapp/app/v3/tracer.server.ts1-100 packages/core/package.json175-195
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.