This document provides a high-level introduction to the Trigger.dev codebase, explaining its purpose as an open-source background jobs framework and providing an overview of the repository structure. For detailed information about specific subsystems:
Trigger.dev is an open-source platform for building, deploying, and managing background tasks and workflows. It provides developers with:
@trigger.dev/sdk packageThe system supports both local development (via trigger dev) and production deployment (via trigger deploy), with tasks executing in isolated worker containers orchestrated by the RunEngine.
Sources: package.json1-116 packages/trigger-sdk/package.json1-131 packages/cli-v3/package.json1-162
Trigger.dev is organized as a pnpm workspace monorepo with build orchestration via Turborepo. The repository contains three primary layers:
| Layer | Purpose | Example Packages |
|---|---|---|
| Applications | Infrastructure services that run the platform | apps/webapp, apps/coordinator, apps/supervisor |
| Public Packages | Published to npm for external developer use | @trigger.dev/sdk, trigger.dev (CLI), @trigger.dev/build |
| Internal Packages | Shared code used internally, not published | @internal/run-engine, @internal/redis, @trigger.dev/database |
Sources: package.json1-116 pnpm-lock.yaml1-107 turbo.json1-89
The following diagram shows how the major code components interact during task execution:
Sources: internal-packages/run-engine/src/engine/index.ts1-304 packages/cli-v3/package.json1-162 apps/webapp/package.json1-294 packages/trigger-sdk/package.json1-131
The following table maps system concepts to their primary code entities:
| System Component | Primary Code Entity | Location | Description |
|---|---|---|---|
| Task Orchestration | RunEngine class | internal-packages/run-engine/src/engine/index.ts76-943 | Central orchestrator managing task lifecycle |
| Queue Management | RunQueue class | internal-packages/run-engine/src/engine/index.ts89 | Fair queue selection and concurrency |
| State Management | ExecutionSnapshotSystem | internal-packages/run-engine/src/engine/index.ts91 | Tracks execution state transitions |
| Run Execution | RunAttemptSystem | internal-packages/run-engine/src/engine/index.ts92 | Handles attempt lifecycle |
| Dequeuing | DequeueSystem | internal-packages/run-engine/src/engine/index.ts93 | Assigns runs to workers |
| Waitpoints | WaitpointSystem | internal-packages/run-engine/src/engine/index.ts94 | Manages task dependencies |
| Checkpointing | CheckpointSystem | internal-packages/run-engine/src/engine/index.ts97 | State persistence for resumption |
| Distributed Locking | RunLocker class | internal-packages/run-engine/src/engine/index.ts78 | Uses Redlock for coordination |
| Database | PrismaClient | internal-packages/run-engine/src/engine/index.ts87 | PostgreSQL via Prisma ORM |
| Cache | Redis client | internal-packages/run-engine/src/engine/index.ts1 | From @internal/redis |
Sources: internal-packages/run-engine/src/engine/index.ts76-943 internal-packages/run-engine/src/engine/systems/runAttemptSystem.ts1-892 internal-packages/run-engine/src/engine/systems/dequeueSystem.ts1-644 internal-packages/run-engine/src/engine/systems/waitpointSystem.ts1-540
The repository uses Changesets for versioning with a fixed versioning strategy for all @trigger.dev/* packages, meaning they always share the same version number.
Sources: .changeset/config.json1-23 turbo.json1-89 package.json1-116 CHANGESETS.md1-67
The .changeset/config.json specifies "fixed": [["@trigger.dev/*", "trigger.dev"]], ensuring all public packages share the same version. The current version across all packages is 4.3.2 as of the latest release.
Sources: .changeset/config.json10 packages/trigger-sdk/CHANGELOG.md1-10 packages/cli-v3/CHANGELOG.md1-5 packages/core/CHANGELOG.md1-5
The webapp uses a comprehensive environment variable system with 250+ configuration options validated via Zod schemas:
Sources: apps/webapp/app/env.server.ts1-708
Key configuration areas include:
The system supports two primary workflows:
Local Development (trigger dev):
Production Deployment (trigger deploy):
BackgroundWorker recordSources: packages/cli-v3/package.json1-162 apps/webapp/package.json1-294 apps/webapp/app/env.server.ts288-343
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.