Repository structure, build system, dependencies, deployment pipeline, and developer experience

How Trigger.dev Is Built

Trigger.dev is built as a pnpm monorepo that combines a Remix dashboard, task orchestration services, provider runtimes, and published TypeScript packages in one repository. This page explains the repo layout, build system, dependencies, and deployment path behind the platform.

For Product Managers

This page answers "how does the engineering team ship Trigger.dev?" — the tools, processes, and infrastructure that turn source code into a running platform. Understanding this helps you grasp engineering timelines, deployment complexity, and maintenance costs.

Repository Structure

Trigger.dev is a pnpm monorepo with Turborepo for build orchestration. Applications, published packages, and internal packages all live in a single Git repository.

trigger.dev/
├── apps/
│   ├── webapp/              ← Remix dashboard + REST API (port 3030)
│   ├── supervisor/          ← Container lifecycle manager
│   ├── coordinator/         ← Worker instance coordination
│   ├── docker-provider/     ← Docker container management
│   └── kubernetes-provider/ ← Kubernetes pod management
├── packages/
│   ├── trigger-sdk/         ← @trigger.dev/sdk — public TypeScript SDK
│   ├── core/                ← @trigger.dev/core — shared types, schemas, tracer
│   ├── cli-v3/              ← trigger.dev CLI (dev, deploy, login)
│   ├── build/               ← @trigger.dev/build — build extensions
│   ├── react-hooks/         ← @trigger.dev/react-hooks — SWR hooks
│   ├── python/              ← @trigger.dev/python — Python runtime
│   ├── rsc/                 ← @trigger.dev/rsc — React Server Components
│   └── schema-to-json/      ← Zod/Yup/Arktype → JSON Schema
├── internal-packages/
│   ├── database/            ← Prisma schema + client
│   ├── run-engine/          ← Run orchestration engine
│   ├── schedule-engine/     ← Cron scheduling
│   ├── redis/               ← Redis client (ioredis)
│   ├── redis-worker/        ← Redis-backed job worker
│   ├── cache/               ← Caching layer
│   ├── clickhouse/          ← ClickHouse analytics client
│   ├── tracing/             ← OpenTelemetry instrumentation
│   ├── tsql/                ← Custom query language for logs
│   ├── replication/         ← ElectricSQL replication
│   ├── otlp-importer/       ← OTLP data ingestion
│   ├── emails/              ← Email templates
│   ├── zod-worker/          ← Zod-based worker
│   └── testcontainers/      ← Test infrastructure
├── references/              ← Example projects (hello-world, prisma, nextjs, etc.)
├── docker/                  ← Docker Compose for dev infrastructure
├── hosting/                 ← Self-hosting configs (Docker + Helm)
├── docs/                    ← Documentation site
├── tests/                   ← E2E test suites
├── .github/                 ← CI workflows
├── turbo.json               ← Turborepo pipeline config
├── pnpm-workspace.yaml      ← Workspace definitions
└── package.json             ← Root config (pnpm 10.23.0, Node 20.20.0)

The 5 Applications

App	Technology	Purpose
webapp	Remix 2 + Express + React 18 + Tailwind	Dashboard UI, REST API, WebSocket coordination, run engine
supervisor	Node.js + Dockerode / K8s client	Container lifecycle management (start, monitor, cleanup)
coordinator	Node.js + Socket.io + tinyexec	Worker instance coordination and execution relay
docker-provider	Node.js + Dockerode	Docker-specific container provisioning
kubernetes-provider	Node.js + @kubernetes/client-node	Kubernetes pod provisioning and management

The 8 Published Packages

Package	npm Name	Purpose
trigger-sdk	`@trigger.dev/sdk`	Task definition, triggering, waiting, scheduling
core	`@trigger.dev/core`	Shared types, schemas, JWT, OTEL, Zod helpers
cli-v3	`trigger.dev`	CLI binary: `trigger dev`, `trigger deploy`, `trigger login`
build	`@trigger.dev/build`	Build extensions (Prisma, Puppeteer, Playwright, etc.)
react-hooks	`@trigger.dev/react-hooks`	SWR-based hooks for run status in React apps
python	`@trigger.dev/python`	Python runtime extension for tasks
rsc	`@trigger.dev/rsc`	React Server Components support
schema-to-json	`@trigger.dev/schema-to-json`	Convert Zod/Yup/Arktype schemas to JSON Schema

The 14 Internal Packages

Package	Purpose
`@internal/database`	Prisma schema + generated client (PostgreSQL)
`@internal/run-engine`	Run orchestration — queue, retry, checkpoint, waitpoint
`@internal/schedule-engine`	Cron evaluation and distributed scheduling
`@internal/redis`	Redis client wrapper (ioredis)
`@trigger.dev/redis-worker`	Fair multi-tenant job worker (DRR queuing)
`@internal/cache`	Caching abstraction
`@internal/clickhouse`	ClickHouse query and schema management
`@internal/tracing`	OpenTelemetry setup and utilities
`@internal/tsql`	Custom query language for log search
`@internal/replication`	ElectricSQL real-time replication
`@internal/otlp-importer`	OTLP data ingestion pipeline
`@internal/emails`	Transactional email templates
`@internal/zod-worker`	Zod-validated background worker
`@internal/testcontainers`	Testcontainers setup for integration tests

Why a Monorepo?

The SDK, CLI, webapp, and worker all share types from @trigger.dev/core. When the team adds a new task option, the type definition in core is immediately available to the SDK, the CLI build system, and the webapp API validation — no publishing, no version drift. Turborepo ensures only affected packages rebuild.

Build System

Package Build Tools

Different packages use different build tools based on their requirements:

Tool	Used By	Why
tshy	SDK, core, build, react-hooks, python, rsc, schema-to-json, CLI	Dual ESM/CJS output for broad compatibility
tsup	redis-worker	Fast bundling for internal packages
esbuild	coordinator, docker-provider, kubernetes-provider	Fast single-file bundling for container apps
tsc	run-engine, supervisor, database	Standard TypeScript compilation

Build Pipeline

pnpm install                    ← installs all deps + runs postinstall
    │                              (fumadocs-mdx for docs)
    ▼
turbo build                     ← Turborepo orchestrates parallel builds
    │
    ├──► @trigger.dev/core       (tshy → dist/esm + dist/commonjs)
    ├──► @trigger.dev/sdk        (tshy → dist/esm + dist/commonjs)
    ├──► trigger.dev (CLI)       (tshy → dist/esm)
    ├──► @internal/database      (prisma generate + tsc)
    ├──► @internal/run-engine    (tsc)
    ├──► webapp                  (remix build → server + client bundles)
    ├──► supervisor              (tsc)
    ├──► coordinator             (esbuild → single file)
    ├──► docker-provider         (esbuild → single file)
    └──► kubernetes-provider     (esbuild → single file)

Versioning and Publishing

pnpm changeset:add           ← developer describes the change
    │
    ▼
pnpm changeset:version       ← bumps versions based on changesets
    │
    ▼
pnpm changeset:release       ← builds + publishes to npm
    │                           uses scripts/updateVersion.ts
    ▼
GitHub Release                ← auto-created with changelog
    │
    ▼
Docker Build (triggered)      ← publishes webapp + worker images to GHCR

Dependency Map

Webapp Dependencies (Key Libraries)

Dependency	Purpose
Remix 2.1.0	Server-rendered React framework
Express 4.20.0	HTTP server with middleware
React 18	UI framework
Tailwind CSS	Utility-first styling
Socket.io	Real-time WebSocket communication
Prisma	PostgreSQL ORM
ioredis	Redis client
graphile-worker	Legacy background jobs
remix-auth	Authentication (GitHub, Google, Magic Link)
@electric-sql/react	Real-time database sync
@opentelemetry/*	Distributed tracing
posthog-js	Product analytics
@sentry/remix	Error tracking

SDK Dependencies

Dependency	Purpose
@opentelemetry/api	Tracing instrumentation
ws	WebSocket client
chalk	CLI colored output
cronstrue	Human-readable cron descriptions
slug	URL-safe identifiers
ulid / uuid	Unique ID generation
evt	Type-safe event emitter

CLI Dependencies

Dependency	Purpose
commander	CLI framework
@clack/prompts	Interactive CLI prompts
chokidar	File watching (hot reload)
esbuild	Task code bundling
magicast	AST-based code modification
partysocket	Reconnecting WebSocket
socket.io-client	Platform communication
@depot/cli	Remote Docker builds

Infrastructure Services

Service	Version	Purpose
PostgreSQL	15+ (pg_partman)	Primary database with table partitioning
Redis	7+	Queue, locks, caching, pub/sub
ClickHouse	25.6+	Analytics, logs, task events
ElectricSQL	Latest	Real-time PostgreSQL replication
S2 (Streamstore)	Latest	Realtime stream data (v2)
MinIO	Latest	S3-compatible object storage (self-hosted)

Deployment

Cloud Platform (cloud.trigger.dev)

The managed cloud runs all five applications plus infrastructure services. Deployments are automated via CI:

Changesets trigger a release PR
Merge publishes npm packages
Docker images are built with Depot (build caching)
Images pushed to GitHub Container Registry (GHCR)
Deployed to production infrastructure

Self-Hosted (Docker Compose)

docker/docker-compose.yml
  ├── database         → PostgreSQL (pg_partman_bgw)
  ├── redis            → Redis 7
  ├── electric         → ElectricSQL
  ├── clickhouse       → ClickHouse 25.6+
  └── webapp           → Remix dashboard + API

hosting/docker/
  ├── webapp/          → Webapp compose config
  └── worker/          → Supervisor compose config

Self-Hosted (Kubernetes / Helm)

Component	Helm Chart
Webapp	Main deployment + service
Supervisor	Worker management deployment
ElectricSQL	Real-time replication
Registry	Container image registry
PostgreSQL	Bitnami subchart
Redis	Bitnami subchart
ClickHouse	Bitnami subchart
MinIO	Bitnami subchart

Deployment Options

Strategy	Target	Complexity
Cloud	cloud.trigger.dev	None — fully managed
Docker Compose	Single server	Low — `docker compose up`
Helm Chart	Kubernetes cluster	Medium — chart version 4.0.5
Custom	Any infrastructure	High — bring your own registry + orchestration

Quality Assurance

Testing

Layer	Tool	Scope
Unit tests	Vitest	Package-level unit tests
Integration tests	Vitest + Testcontainers	Run engine, Redis worker, ClickHouse (with real services)
E2E tests	Playwright + CLI	Full deploy → trigger → execute → verify
SDK compatibility	Custom harness	Cross-version SDK testing

CI/CD Workflows

Workflow	Trigger	Purpose
`release.yml`	Changeset merge	Build, typecheck, npm publish, Docker build
`publish.yml`	Release tag	Docker image publish (webapp + workers)
`unit-tests.yml`	PR	Webapp, packages, internal unit tests
`unit-tests-packages.yml`	PR	Testcontainers-based integration tests
`e2e.yml`	PR	CLI E2E on Ubuntu/Windows, npm/pnpm
`typecheck.yml`	PR	Full monorepo type checking
`sdk-compat.yml`	PR	SDK cross-version compatibility

Code Quality

Tool	Purpose
TypeScript strict mode	Type safety across all packages
Changesets	Semver-compliant versioning
Turbo cache	Skip unchanged package builds
Depot	Fast Docker image builds with caching

Developer Experience

Getting Started

# Prerequisites: Node 20.20.0, pnpm 10.23.0, Docker, protobuf

# Clone and install
git clone https://github.com/triggerdotdev/trigger.dev && cd trigger.dev
pnpm install

# Copy env and set encryption key
cp .env.example .env

# Start infrastructure
pnpm run docker    # PostgreSQL, Redis, ElectricSQL, ClickHouse

# Run database migrations
pnpm run db:migrate

# Build required packages
pnpm run build --filter webapp
pnpm run build --filter trigger.dev
pnpm run build --filter @trigger.dev/sdk

# Start the webapp
pnpm run dev --filter webapp    # Dashboard at http://localhost:3030

Key Developer Commands

Task	Command
Start webapp	`pnpm run dev --filter webapp`
Build everything	`pnpm run build`
Run all tests	`pnpm test`
Run webapp tests	`pnpm test:webapp`
Run package tests	`pnpm test:packages`
Type check	`turbo typecheck`
DB migrations	`pnpm run db:migrate`
Start Docker infra	`pnpm run docker`

Reference Projects

The references/ directory contains example projects for testing the SDK and CLI:

Reference	Purpose
`hello-world`	Basic SDK + CLI integration test
`prisma-6` / `prisma-7`	Prisma build extension testing
`nextjs-realtime`	Next.js + React hooks integration
`d3-chat`	AI chat with streaming
`effect`	Effect TS integration

For PMs: Why Reference Projects?

Reference projects are real working examples that double as integration tests. When the team changes the SDK, they run these projects to verify nothing breaks. This is cheaper than maintaining a full E2E test suite for every use case, and the projects also serve as documentation for users.

How Trigger.dev Is Built

How Trigger.dev Is Built

Repository Structure

The 5 Applications

The 8 Published Packages

The 14 Internal Packages

Build System

Package Build Tools

Build Pipeline

Versioning and Publishing

Dependency Map

Webapp Dependencies (Key Libraries)

SDK Dependencies

CLI Dependencies

Infrastructure Services

Deployment

Cloud Platform (cloud.trigger.dev)

Self-Hosted (Docker Compose)

Self-Hosted (Kubernetes / Helm)

Deployment Options

Quality Assurance

Testing

CI/CD Workflows

Code Quality

Developer Experience

Getting Started

Key Developer Commands

Reference Projects

What's Next

What Is Trigger.dev?

Trigger.dev Architecture Overview

Trigger.dev Workflows and Data Flows

On this page