AGENTS.md · triggerdotdev/trigger.dev

Sections

1. Build and Development Commands
2. Testing
3. Code Style
4. Changesets and Server Changes
5. Dependency Pinning
6. Architecture Overview
7. Docker Image Guidelines
8. Writing Trigger.dev Tasks
9. Testing with the hello-world Reference Project
10. Local Task Testing Workflow
11. agentcrumbs

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

This file provides guidance to Claude Code when working with this repository. Subdirectory AGENTS.md files provide deeper context when you navigate into specific areas.

## Build and Development Commands

This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`.

**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.

```bash
pnpm run docker              # Core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite)
# pnpm run docker:full       # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling
pnpm run db:migrate           # Run database migrations
pnpm run db:seed              # Seed the database (required for reference projects)

# Build packages (required before running)
pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk

pnpm run dev --filter webapp  # Run webapp (http://localhost:3030)
pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"  # Watch CLI and packages
```

### Verifying Changes

The verification command depends on where the change lives:

- **Apps and internal packages** (`apps/*`, `internal-packages/*`): Use `typecheck`. **Never use `build`** for these — building proves almost nothing about correctness.
- **Public packages** (`packages/*`): Use `build`.

```bash
# Apps and internal packages — use typecheck
pnpm run typecheck --filter webapp                  # ~1-2 minutes
pnpm run typecheck --filter @internal/run-engine

# Public packages — use build
pnpm run build --filter @trigger.dev/sdk
pnpm run build --filter @trigger.dev/core
```

Only run typecheck/build after major changes (new files, significant refactors, schema changes). For small edits, trust the types and let CI catch issues.

## Testing

We use vitest exclusively. **Never mock anything** - use testcontainers instead.

Prefer integration tests that exercise real production behavior and dependencies. Before adding a unit test, name the specific regression it catches that no existing test, type, or CI suite catches. If you can't, don't add it. A test that only restates the condition you just wrote, or still passes when the logic it covers is broken, is not worth adding. Put the regression in a one-line comment: `// Catches: <bug>`. Avoid tests coupled to implementation details, source spelling, CSS, markup or copy. Do not duplicate production logic in tests or add redundant cases. Verify new tests are discovered by the intended suite. We have historical unit tests; this is not evidence that new unit tests should be added.

```bash
pnpm run test --filter webapp                          # All tests for a package
cd internal-packages/run-engine
pnpm run test ./src/engine/tests/ttl.test.ts --run     # Single test file
pnpm run build --filter @internal/run-engine           # May need to build deps first
```

Where test files go:

- **Webapp:** put tests in `apps/webapp/test/`, not next to the source. Vitest there only runs files matched by the `include` list in `apps/webapp/vitest.config.ts`.
- **Packages:** follow the package's existing layout. Next to the source (`MyService.ts` -> `MyService.test.ts`) and a `test/` folder are both fine.

### Testcontainers for Redis/PostgreSQL

```typescript
import { redisTest, postgresTest, containerTest } from "@internal/testcontainers";

redisTest("should use redis", async ({ redisOptions }) => {
  /* ... */
});
postgresTest("should use postgres", async ({ prisma }) => {
  /* ... */
});
containerTest("should use both", async ({ prisma, redisOptions }) => {
  /* ... */
});
```

## Code Style

### Formatting and linting

Format and lint are enforced by CI (`code-quality` check). Run before committing:

```bash
pnpm run format      # oxfmt — auto-fixes formatting
pnpm run lint:fix    # oxlint — auto-fixes lint violations
pnpm run lint        # oxlint — check only (no fixes)
```

### Dead code

We use knip to control unused dependencies and code. It is enforced by CI `code-quality`.

Scan your code before pushing with:

```bash
pnpm run knip
```

If there are false positives, edit ./knip.ts so that it passes.

### Imports

**Prefer static imports over dynamic imports.** Only use dynamic `import()` when:
- Circular dependencies cannot be resolved otherwise
- Code splitting is genuinely needed for performance
- The module must be loaded conditionally at runtime

Dynamic imports add unnecessary overhead in hot paths and make code harder to analyze. If you find yourself using `await import()`, ask if a regular `import` statement would work instead.

## Changesets and Server Changes

Changesets and `.server-changes/` files are **user-facing release notes**. They ship verbatim into the changelog that customers read to decide what to upgrade for or pay attention to. They are not a catalog of every change: anyone who wants the exact history reads the commits. So the question is not "did I touch a public package or a server app?" but **"would a user or customer care about this change?"**

**Add one** when the change is something a user would notice, act on, or want to hear about: a new feature, a bug fix they could have hit, a behavior or performance change they would feel, a breaking change.

**Skip it** (no changeset, no `.server-changes/` file) when the change is not worth communicating to users, even if it touches a public package or a server app. For example:

- internal-only or admin-only changes, refactors, test-only changes, chores
- performance or query tuning with no user-visible behavior change
- changes to a public package that is not consumed independently (e.g. `@trigger.dev/redis-worker`), where a version bump means nothing to a user

When in doubt, ask a maintainer rather than adding a note by default. An unnecessary entry is noise in the changelog, not a safe default.

### How to add one

When a **public package** (`packages/*` or `integrations/*`) change is user-facing, add a changeset:

```bash
pnpm run changeset:add
```

- Default to **patch** for bug fixes and minor changes
- Confirm with maintainers before selecting **minor** (new features)
- **Never** select major without explicit approval

When a **server-only** change (`apps/webapp/`, `apps/supervisor/`, etc., with no package changes) is user-facing, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation.

**Write the description for users, not maintainers.** Both changesets and `.server-changes/` notes ship verbatim in user-visible release notes. Lead with what changed *for the user*: one plain sentence describing behavior, not implementation, and never naming internal tools or infra. The full writing guidance in `.server-changes/README.md` applies to changesets too.

## Dependency Pinning

Zod is pinned to a single version across the entire monorepo. When adding zod to a new or existing package, use the **exact same version** as the rest of the repo - never a different version or a range. Mismatched zod versions cause runtime type incompatibilities (e.g., schemas from one package can't be used as body validators in another).

## Architecture Overview

### Request Flow

User API call -> Webapp routes -> Services -> RunEngine -> Redis Queue -> Supervisor -> Container execution -> Results back through RunEngine -> ClickHouse (analytics) + PostgreSQL (state)

### Apps

- **apps/webapp**: Remix 2.17.4 app - main API, dashboard, orchestration. Uses Express server.
- **apps/supervisor**: Manages task execution containers (Docker/Kubernetes).

### Public Packages

- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK for writing tasks
- **packages/cli-v3** (`trigger.dev`): CLI - also bundles code that goes into customer task images
- **packages/core** (`@trigger.dev/core`): Shared types. **Import subpaths only** (never root).
- **packages/build** (`@trigger.dev/build`): Build extensions and types