This document details the organization of the Trigger.dev monorepo, describing the structure and purpose of the apps/, packages/, and internal-packages/ directories. For information about the build system that orchestrates these packages, see Build System and Turborepo. For dependency management strategies across packages, see Dependency Management.
The Trigger.dev monorepo follows a workspace-based architecture managed by pnpm, with three primary top-level directories for code organization:
Workspace Configuration
The workspace is defined in package.json4-8 at the repository root:
| Configuration | Value | Purpose |
|---|---|---|
packageManager | [email protected] | Enforces exact pnpm version |
workspaces | ["apps/*", "packages/*", "integrations/*"] | Defines workspace members |
| Dependency protocol | workspace:* or workspace:^version | Links local packages |
Sources: package.json1-114 pnpm-lock.yaml1-100
The apps/ directory contains deployable applications and services. These are not published to npm but are deployed as standalone services or containers.
The primary web application built with Remix, serving as both the API server and web dashboard.
Key Characteristics:
| Aspect | Implementation |
|---|---|
| Framework | Remix 2.1.0 with Express adapter |
| Build configuration | apps/webapp/remix.config.js1-42 |
| Server bundling | All @internal/* and @trigger.dev/* packages bundled |
| Database access | Via @internal/database (Prisma) |
| Task execution | Via @internal/run-engine |
| Background jobs | Via @internal/zod-worker (graphile-worker) |
Package Dependencies (Selected):
From apps/webapp/package.json28-219:
@remix-run/express, @remix-run/node, @remix-run/react (Remix framework)@internal/run-engine, @internal/cache, @internal/schedule-engine (execution layer)@trigger.dev/sdk, @trigger.dev/core (task definitions)socket.io 4.7.4 (realtime communication)graphile-worker 0.16.6 (background job processing)ioredis 5.3.2 (Redis client)Sources: apps/webapp/package.json1-291 apps/webapp/remix.config.js1-42 pnpm-lock.yaml202-973
A standalone Socket.io service for coordinating communication between workers and the webapp.
Package Structure:
| File | Purpose |
|---|---|
| apps/coordinator/package.json1-128 | Package definition |
| Dependencies | socket.io, @trigger.dev/core, prom-client |
| Build tool | esbuild 0.19.11 |
| Dev runtime | tsx 4.7.0 |
Sources: pnpm-lock.yaml102-128 apps/coordinator/package.json1-128
Worker coordinator that manages task execution processes, handles checkpointing, and orchestrates Docker/Kubernetes workers.
Key Dependencies:
From pnpm-lock.yaml171-200:
socket.io 4.7.4 (coordinator connection)dockerode 4.0.6 (Docker API client)@kubernetes/client-node 1.0.0 (Kubernetes API)@aws-sdk/client-ecr 3.839.0 (ECR authentication)@trigger.dev/core (shared schemas and utilities)Sources: pnpm-lock.yaml171-200
Provider services that implement runtime-specific logic for managing task execution containers/pods.
Common Pattern:
Both providers share similar structure:
@trigger.dev/core, execa/@kubernetes/client-nodeSources: pnpm-lock.yaml130-169
The packages/ directory contains public npm packages published under the @trigger.dev/* scope (and trigger.dev for the CLI).
The primary SDK for defining and triggering tasks.
Export Structure:
From packages/trigger-sdk/package.json23-28:
| Export | Source | Purpose |
|---|---|---|
. | ./src/v3/index.ts | Main SDK API (task, triggers, schedules) |
./v3 | ./src/v3/index.ts | Explicit v3 API |
./ai | ./src/v3/ai.ts | AI SDK integration utilities |
Build Configuration:
| Property | Value | Notes |
|---|---|---|
| Build tool | tshy 3.0.2 | Dual ESM/CJS |
| Type | module | ESM by default |
| Main | ./dist/commonjs/v3/index.js | CJS entry |
| Module | ./dist/esm/v3/index.js | ESM entry |
| Peer deps | zod ^3.0.0 || ^4.0.0, ai ^4.2.0 || ^5.0.0 (optional) |
Key Dependencies:
From packages/trigger-sdk/package.json52-64:
@trigger.dev/core workspace:4.3.0 (shared functionality)@opentelemetry/api 1.9.0 (tracing)ws 8.11.0 (WebSocket communication)evt 2.4.13 (event handling)ulid 2.3.0 (ID generation)Sources: packages/trigger-sdk/package.json1-132 packages/trigger-sdk/CHANGELOG.md1-100
Command-line interface for local development and deployment.
Package Details:
| Property | Value |
|---|---|
| Package name | trigger.dev |
| Binary | ./dist/esm/index.js |
| Build tool | tshy (ESM only) |
| MCP server | Yes (mcpName: io.github.triggerdotdev/trigger.dev) |
Core Dependencies:
From packages/cli-v3/package.json83-148:
@trigger.dev/build, @trigger.dev/core, @trigger.dev/schema-to-json (workspace deps)esbuild 0.23.0 (bundling)@depot/cli (remote builds)chokidar (file watching)socket.io-client 4.7.5 (coordinator connection)c12 (config loading)Sources: packages/cli-v3/package.json1-163 packages/cli-v3/CHANGELOG.md1-100
Shared core functionality used across SDK, CLI, and platform.
Export Structure (Extensive):
From packages/core/package.json22-55 the package exports ~20 subpaths including:
| Export | Purpose |
|---|---|
. | Main core utilities |
./v3 | V3-specific APIs |
./v3/schemas | Zod schemas |
./v3/otel | OpenTelemetry utilities |
./v3/zodfetch | Type-safe fetch wrapper |
./v3/zodSocket | Type-safe Socket.io wrapper |
./v3/workers | Worker communication protocols |
./v3/runEngineWorker | Run engine worker interfaces |
Key Dependencies:
From packages/core/package.json168-201:
zod 3.25.76, zod-error, zod-validation-errorsocket.io 4.7.4, socket.io-client 4.7.5superjson 2.2.1 (serialization)jose 5.4.0 (JWT)Sources: packages/core/package.json1-582 packages/core/CHANGELOG.md1-100
Build extensions for customizing Docker image builds.
Extension Exports:
From packages/build/package.json23-35:
| Export | Purpose |
|---|---|
./extensions | Main extension API |
./extensions/core | Core utilities |
./extensions/prisma | Prisma client generation |
./extensions/audioWaveform | Audio processing |
./extensions/typescript | TypeScript compilation |
./extensions/puppeteer | Puppeteer/Chromium |
./extensions/playwright | Playwright |
./extensions/lightpanda | Lightpanda browser |
Dependencies:
From packages/build/package.json79-86:
@prisma/config 6.10.0 (Prisma configuration parsing)@trigger.dev/core workspace depmlly, pkg-types, resolve, tinyglobby, tsconfck (build utilities)Sources: packages/build/package.json1-216 packages/build/CHANGELOG.md1-100
React hooks for frontend integration with Trigger.dev.
Package Structure:
| Property | Value |
|---|---|
| Main export | ./src/index.ts |
| Dependencies | @trigger.dev/core, swr 2.2.5 |
| Peer deps | react ^18.0 || ^19.0, react-dom ^18.0 || ^19.0 |
Sources: packages/react-hooks/package.json1-76 packages/react-hooks/CHANGELOG.md1-50
React Server Components integration.
Unique Aspect:
From packages/rsc/package.json42-43 this package bundles React 19 RC:
react 19.0.0-rc.1react-dom 19.0.0-rc.1Sources: packages/rsc/package.json1-76 packages/rsc/CHANGELOG.md1-50
Redis-based worker queue implementation.
Build Tool Difference:
Unlike other packages using tshy, this uses tsup
Dependencies:
@trigger.dev/corelodash.omitnanoid 5.0.7p-limit 6.2.0seedrandom, zod, cron-parserSources: packages/redis-worker/package.json1-57 packages/redis-worker/CHANGELOG.md1-50
The internal-packages/ directory contains packages used exclusively within the monorepo. These are not published to npm but are shared across apps and packages using workspace dependencies.
Prisma database schema and client.
Contents:
| Component | Location |
|---|---|
| Schema | internal-packages/database/prisma/schema.prisma |
| Migrations | internal-packages/database/prisma/migrations/ |
| Client | @prisma/client 6.14.0 |
Usage Pattern:
From apps/webapp/package.json474-476 and other apps:
"@trigger.dev/database": "workspace:*"
Generated client is built during docker/scripts/entrypoint.sh9-11:
Sources: internal-packages/database pnpm-lock.yaml1019-1036 docker/scripts/entrypoint.sh1-40
Core task execution orchestration engine.
Key Responsibilities:
From dependencies in pnpm-lock.yaml1131-1165:
@trigger.dev/database)@internal/redis, @trigger.dev/redis-worker)@internal/cache)@internal/tracing)@trigger.dev/core)Used By:
apps/webapp - Primary consumerSources: pnpm-lock.yaml1131-1165
Caching layer built on Unkey cache library.
Dependencies:
From pnpm-lock.yaml976-992:
@internal/redis (Redis backend)@trigger.dev/core (shared utilities)@unkey/cache 1.5.0 (cache implementation)@unkey/error 0.2.0 (error handling)superjson 2.2.1 (serialization)Sources: pnpm-lock.yaml976-992
ClickHouse database integration for analytics.
Schema Management:
From docker/Dockerfile59-61:
Migrations run via docker/scripts/entrypoint.sh13-26 using Goose.
Dependencies:
From pnpm-lock.yaml994-1017:
@clickhouse/client 1.12.1@internal/tracing@trigger.dev/corezod 3.25.76Sources: pnpm-lock.yaml994-1017 docker/Dockerfile59-61 docker/scripts/entrypoint.sh13-26
Redis client wrapper around ioredis.
Simple Structure:
From pnpm-lock.yaml1094-1101:
@trigger.dev/coreioredis 5.3.2Used by: @internal/cache, @internal/run-engine, @internal/replication, @internal/schedule-engine
Sources: pnpm-lock.yaml1094-1101
OpenTelemetry tracing utilities.
Used By:
@internal/clickhouse (for instrumentation)@internal/replication (for trace context)@internal/run-engine (for task tracing)apps/webapp (for API tracing)Sources: apps/webapp/package.json298-299
Background job processing using graphile-worker with Zod schema validation.
Dependencies:
Depends on @trigger.dev/database for PostgreSQL connection.
Used By:
apps/webapp for background job execution (e.g., deployments, cleanup, notifications).
Sources: apps/webapp/package.json300-302
Cron schedule management and execution.
Used By:
apps/webapp for scheduled task triggers.
Sources: apps/webapp/package.json294-296
@internal/replication:
Database replication logic using:
@internal/redis (replication state)pg 8.15.6 (PostgreSQL logical replication)redlock 5.0.0-beta.2 (distributed locks)@internal/otlp-importer:
OpenTelemetry Protocol importer:
protobufjs 7.3.2 (protocol buffers)long 5.2.3 (64-bit integers)Sources: pnpm-lock.yaml1103-1129 pnpm-lock.yaml1075-1092
@internal/testcontainers:
Test utilities for spinning up Docker containers in tests (used in devDependencies).
emails:
Email template rendering:
@react-email/components 0.0.16@react-email/render 0.0.12nodemailer 7.0.11resend 3.2.0Sources: pnpm-lock.yaml1038-1073
The monorepo uses pnpm's workspace protocol for internal dependencies:
| Pattern | Example | Meaning |
|---|---|---|
workspace:* | "@internal/cache": "workspace:*" | Any version in workspace |
workspace:^version | "@trigger.dev/core": "workspace:4.3.0" | Specific version constraint |
From .changeset/config.json10:
This ensures all public @trigger.dev/* packages and trigger.dev CLI maintain synchronized versions.
Defined in turbo.json4-7:
The ^ caret means "wait for dependencies to build first", establishing a topological build order.
Sources: .changeset/config.json1-26 turbo.json1-100 package.json69
Pattern Summary:
@trigger.dev/* scope (except CLI which is trigger.dev)@internal/* scope (with exception of emails)Sources: package.json1-114 pnpm-lock.yaml1-200
Refresh this wiki