---
title: "How Trigger.dev Is Built"
description: "Repository structure, build system, dependencies, deployment pipeline, and developer experience"
image: "https://tractiongrowth.com/og/open-source/trigger-dev-background-jobs/how-it-is-built/image.png"
---

# How Trigger.dev Is Built

# 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.

<Callout title="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.
</Callout>

## 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              |

<Callout type="info" title="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.
</Callout>

## 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:

1. **Changesets** trigger a release PR
2. Merge publishes npm packages
3. Docker images are built with **Depot** (build caching)
4. Images pushed to GitHub Container Registry (GHCR)
5. 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

```bash
# 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             |

<Callout type="info" title="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.
</Callout>

## What's Next

<Cards>
  <Card title="What Is Trigger.dev?" description="What Trigger.dev does, who it's for, and why it exists." href="/open-source/trigger-dev-background-jobs" />

  <Card title="Trigger.dev Architecture Overview" description="Service layout, run engine design, and execution infrastructure." href="/open-source/trigger-dev-background-jobs/architecture" />

  <Card title="Trigger.dev Workflows and Data Flows" description="Key user journeys traced through SDK, API, run engine, and workers." href="/open-source/trigger-dev-background-jobs/workflows" />
</Cards>