Trigger.dev is an open-source background jobs framework that enables developers to define, schedule, and execute long-running tasks with built-in reliability, observability, and lifecycle management. This page provides a high-level overview of the system architecture, core components, and how they interact to deliver a complete task execution platform.
For detailed information about specific subsystems:
Trigger.dev is a platform for building reliable background jobs in TypeScript/JavaScript. It consists of:
The system is architected as a monorepo using pnpm workspaces and Turborepo for coordinated builds.
Sources: pnpm-lock.yaml1-49 package.json1-121 turbo.json1-80
Core Package Organization:
| Package | Location | Purpose |
|---|---|---|
@trigger.dev/sdk | packages/trigger-sdk | Task definition API, lifecycle hooks, triggering |
trigger.dev (CLI) | packages/cli-v3 | Development server, deployment, MCP server |
@trigger.dev/core | packages/core | Shared runtime logic, schemas, utilities |
@trigger.dev/build | packages/build | Build extensions (Prisma, ffmpeg, etc.) |
@trigger.dev/react-hooks | packages/react-hooks | Realtime UI integration hooks |
webapp | apps/webapp | Remix dashboard + API server |
@trigger.dev/database | internal-packages/database | Prisma schema and client |
@internal/run-engine | internal-packages/run-engine | Task orchestration engine |
@internal/cache | internal-packages/cache | Redis caching abstraction |
Sources: package.json1-121 pnpm-lock.yaml50-1150 packages/trigger-sdk/package.json1-131 packages/cli-v3/package.json1-162 apps/webapp/package.json1-301
The following diagram shows how developers interact with Trigger.dev from defining a task through to its execution:
Key Code Entities:
| Entity | Location | Description |
|---|---|---|
task() | packages/trigger-sdk/src/v3/index.ts | Main function to define tasks |
TriggerTaskService | apps/webapp/app/v3/services/triggerTask.server.ts | Server-side triggering logic |
DequeueSystem | internal-packages/run-engine/src/dequeue/ | Fair queue selection and run dequeuing |
TaskExecutor | packages/core/src/v3/workers/index.ts | Worker-side task execution orchestrator |
WorkerDeployment | internal-packages/database/prisma/schema.prisma1700-1800 | Database model for deployments |
Sources: packages/trigger-sdk/package.json1-131 packages/cli-v3/package.json1-162 apps/webapp/package.json28-228
Run Engine Systems:
| System | Location | Responsibility |
|---|---|---|
TriggerSystem | internal-packages/run-engine/src/ | Creates TaskRun records with validation |
EnqueueSystem | internal-packages/run-engine/src/ | Adds runs to Redis-backed queues |
DequeueSystem | internal-packages/run-engine/src/dequeue/ | Selects runs using fair queue algorithm |
WaitpointSystem | internal-packages/run-engine/src/ | Manages wait.for(), wait.until() pausing |
CheckpointSystem | internal-packages/run-engine/src/ | Suspends/restores execution state to S3 |
RunLocker | internal-packages/run-engine/src/ | Distributed mutual exclusion via Redlock |
TaskExecutor | packages/core/src/v3/workers/TaskExecutor.ts | Executes task code in worker process |
Sources: apps/webapp/app/env.server.ts405-520 internal-packages/database/prisma/schema.prisma1-300
Trigger.dev uses a multi-database architecture optimized for different access patterns:
| Storage System | Technology | Purpose | Configuration |
|---|---|---|---|
| Primary Database | PostgreSQL | Organizations, projects, task runs, deployments | DATABASE_URL in apps/webapp/app/env.server.ts52-66 |
| Read Replica (optional) | PostgreSQL | Read-heavy queries for presenters | DATABASE_READ_REPLICA_URL in apps/webapp/app/env.server.ts67 |
| Queue & Cache | Redis | Run queues, distributed locks, rate limiting | Multiple instances: apps/webapp/app/env.server.ts118-261 |
| Observability | ClickHouse | OTLP traces, logs, analytics events | internal-packages/clickhouse |
| Object Storage | S3/Compatible | Checkpoint data, large payloads, artifacts | apps/webapp/app/env.server.ts345-355 |
Redis Instance Separation:
Trigger.dev uses separate Redis instances for different concerns to prevent resource contention:
Prisma Schema Key Models:
| Model | Location | Description |
|---|---|---|
Organization | internal-packages/database/prisma/schema.prisma174-228 | Multi-tenant organization entity |
Project | internal-packages/database/prisma/schema.prisma300-400 | Container for environments and tasks |
RuntimeEnvironment | internal-packages/database/prisma/schema.prisma500-600 | Development, staging, production envs |
TaskRun | internal-packages/database/prisma/schema.prisma1000-1200 | Individual task execution record |
TaskRunAttempt | internal-packages/database/prisma/schema.prisma1300-1400 | Retry attempt within a run |
WorkerDeployment | internal-packages/database/prisma/schema.prisma1700-1800 | Container image deployment |
Sources: apps/webapp/app/env.server.ts1-600 internal-packages/database/prisma/schema.prisma1-300
The webapp is a Remix application following a layered architecture:
Key Application Files:
| File | Purpose |
|---|---|
| apps/webapp/app/root.tsx1-138 | Root Remix component with global providers |
| apps/webapp/app/entry.server.tsx1-200 | Server-side entry point, bootstrapping, workers |
| apps/webapp/app/entry.client.tsx1-14 | Client-side hydration entry point |
| apps/webapp/server.ts1-300 | Express server with Socket.io, rate limiting |
| apps/webapp/app/env.server.ts1-800 | Environment variable validation with Zod |
Services Pattern:
Services in apps/webapp/app/services/ encapsulate business logic with side effects. Examples:
TriggerTaskService: Validates and triggers task runsDeploymentService: Manages container builds and registry operationsAlertsService: Sends notifications via email/SlackPresenters Pattern:
Presenters in apps/webapp/app/presenters/ aggregate read-only data for display. They:
Sources: apps/webapp/package.json1-301 apps/webapp/app/root.tsx1-138 apps/webapp/app/entry.server.tsx1-200 apps/webapp/server.ts1-300
Trigger.dev supports three deployment strategies:
Deployment Configuration:
| Config | Location | Purpose |
|---|---|---|
DEPLOY_REGISTRY_HOST | apps/webapp/app/env.server.ts295 | Container registry hostname |
DEPLOY_REGISTRY_NAMESPACE | apps/webapp/app/env.server.ts298 | Registry namespace (default: "trigger") |
DEPOT_TOKEN | apps/webapp/app/env.server.ts290 | Depot.dev authentication |
DEPLOY_IMAGE_PLATFORM | apps/webapp/app/env.server.ts335 | Target platform (default: linux/amd64) |
Build Extensions:
Build extensions in packages/build/src/extensions/ customize the deployment image:
| Extension | File | Purpose |
|---|---|---|
prismaExtension | packages/build/src/extensions/prisma.ts | Generate Prisma client, run migrations |
syncVercelEnvVars | packages/build/src/extensions/core.ts | Import Vercel environment variables |
ffmpegExtension | packages/build/src/extensions/audioWaveform.ts | Install ffmpeg binary |
puppeteerExtension | packages/build/src/extensions/puppeteer.ts | Install Chromium dependencies |
playwrightExtension | packages/build/src/extensions/playwright.ts | Install Playwright browsers |
Sources: packages/cli-v3/package.json1-162 packages/build/package.json1-180 apps/webapp/app/env.server.ts288-355
The monorepo uses Changesets for version management and coordinated releases:
CI Configuration:
| Workflow | Location | Purpose |
|---|---|---|
| Changesets PR | .github/workflows/changesets.yml | Auto-create release PR |
| Release | .github/workflows/release.yml | Publish to npm & GitHub |
| Tests | .github/workflows/test.yml | Parallel test execution |
| E2E | .github/workflows/e2e.yml | End-to-end testing |
Version Management:
package.json versions managed automaticallypnpm-lock.yaml updated on releaseSources: package.json1-121 pnpm-lock.yaml1-49 turbo.json1-80
Trigger.dev provides three complementary tools for AI-assisted development:
The Model Context Protocol server exposes Trigger.dev APIs to AI assistants:
| Tool | Implementation | Purpose |
|---|---|---|
search_docs | packages/cli-v3/src/commands/mcp.ts | Search documentation |
trigger_task | packages/cli-v3/src/commands/mcp.ts | Execute task runs |
list_runs | packages/cli-v3/src/commands/mcp.ts | View run history |
deploy | packages/cli-v3/src/commands/mcp.ts | Deploy projects |
get_current_worker | packages/cli-v3/src/commands/mcp.ts | Get deployment info |
Installation: npx trigger.dev mcp
Portable instruction sets in .trigger/skills/ that teach AI assistants correct patterns:
trigger-setup: Project initializationtrigger-tasks: Task definition patternstrigger-agents: AI agent integrationtrigger-realtime: Streaming and SSEInstallation: npx trigger.dev skills add <skill-name>
Comprehensive guidance files in .trigger/AGENTS.md providing:
Installation: npx trigger.dev rules install
Sources: packages/cli-v3/package.json15-16 packages/cli-v3/src/commands/mcp.ts
Trigger.dev uses OpenTelemetry for comprehensive observability:
Observability Configuration:
| Config | Location | Purpose |
|---|---|---|
INTERNAL_OTEL_TRACE_EXPORTER_URL | apps/webapp/app/env.server.ts408 | Internal trace endpoint |
DEV_OTEL_EXPORTER_OTLP_ENDPOINT | apps/webapp/app/env.server.ts374 | Dev environment traces |
| External exporters | trigger.config.ts | User-configured destinations |
Trace Attributes:
Semantic attributes in packages/core/src/v3/semanticInternalAttributes.ts include:
trigger.run.id: Unique run identifiertrigger.task.id: Task identifiertrigger.attempt.number: Retry attempttrigger.environment.id: Environment identifierSources: apps/webapp/app/env.server.ts373-423 packages/core/package.json170-203
This overview provides a foundation for understanding Trigger.dev's architecture. For deeper dives into specific subsystems, refer to the linked sections in the wiki table of contents.
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.