Build Extensions are modular plugins that customize the Docker image build process for Trigger.dev deployments. They allow developers to install system dependencies, configure runtime environments, and integrate external tools (like Prisma, Puppeteer, or FFmpeg) into their task execution environments.
This document covers:
prismaExtension, puppeteerExtension, etc.)trigger.config.tsFor information about the deployment process itself, see Deployment Process. For Docker image building mechanics, see Docker Build Pipeline.
Build Extensions hook into the bundling and image building phases of the Trigger.dev deployment pipeline. They modify the Docker image that will execute tasks in production.
Sources: packages/cli-v3/src/commands/deploy.ts371-410 packages/cli-v3/src/deploy/buildImage.ts58-122 packages/build/package.json23-35
Extensions implement a standard interface defined in the @trigger.dev/build package. Each extension can contribute to multiple phases of the build process.
Sources: packages/build/package.json23-35 packages/cli-v3/src/commands/deploy.ts449-487
The @trigger.dev/build/extensions package provides several production-ready extensions for common dependencies.
| Extension | Package | Purpose | Key Features |
|---|---|---|---|
prismaExtension | @trigger.dev/build/extensions/prisma | Prisma ORM integration | 3 modes (Legacy, Engine-Only, Modern), schema generation, migrations, TypedSQL |
puppeteerExtension | @trigger.dev/build/extensions/puppeteer | Headless Chrome automation | Chromium dependencies, font support |
playwrightExtension | @trigger.dev/build/extensions/playwright | Multi-browser automation | Browser binaries, WebKit/Firefox support |
pythonExtension | @trigger.dev/build/extensions/python | Python runtime | Python 3.x, pip packages |
ffmpegExtension | @trigger.dev/build/extensions/ffmpeg | Media processing | FFmpeg binaries, codec support |
audioWaveformExtension | @trigger.dev/build/extensions/audioWaveform | Audio visualization | Waveform generation tools |
lightpandaExtension | @trigger.dev/build/extensions/lightpanda | Lightweight browser | Alternative to Puppeteer |
typescriptExtension | @trigger.dev/build/extensions/typescript | TypeScript tooling | Enhanced TS support |
Sources: packages/build/package.json28-34 packages/build/CHANGELOG.md36-470
The prismaExtension is the most complex built-in extension, supporting multiple Prisma versions and deployment strategies.
Mode Selection Matrix:
| Prisma Version | Generator Provider | Recommended Mode | Notes |
|---|---|---|---|
| < 6.0 | prisma-client-js | Legacy | Older Prisma versions |
| 6.0 - 6.15 | prisma-client-js | Legacy | Standard setup |
| 6.7+ | prisma-client-js | Legacy | Multi-file schema support |
| 6.16+ | prisma-client-js | Engine-Only | Custom output paths |
| 6.16+ | prisma-client + engineType: "client" | Modern | New architecture |
| 7.0+ (beta) | prisma-client | Modern | Prisma 7 with new architecture |
Sources: packages/build/CHANGELOG.md36-470
Sources: packages/build/CHANGELOG.md64-80
Schema must include correct binary targets:
Sources: packages/build/CHANGELOG.md146-209
Sources: packages/build/CHANGELOG.md212-286
Installs Chromium and required system dependencies for Puppeteer-based browser automation.
Installed APT packages:
Sources: packages/build/package.json32
Adds Python runtime and pip for executing Python scripts from Node.js tasks.
Sources: Diagram 7 (from high-level system architecture)
Installs FFmpeg for media processing tasks.
Sources: Diagram 7 (from high-level system architecture)
Extensions can also synchronize environment variables from external services during deployment.
The syncVercelEnvVars extension automatically imports environment variables from a Vercel project.
Behavior:
process.env during Vercel buildSources: packages/build/CHANGELOG.md21
Syncs environment variables from Neon database projects, with automatic branch detection.
Automatic Branch Mapping:
.env fileSources: packages/build/CHANGELOG.md21
Extensions execute at specific points during the build and deployment process.
Sources: packages/cli-v3/src/commands/deploy.ts371-410 packages/cli-v3/src/deploy/buildImage.ts58-122
Extensions modify the BuildManifest object, which controls image generation:
| Manifest Field | Type | Purpose | Modified By |
|---|---|---|---|
deploy.sync.env | Record<string, string> | Environment variables to sync to deployment | syncVercelEnvVars, syncNeonEnvVars |
deploy.sync.parentEnv | Record<string, string> | Environment variables to sync to parent environment | Branch-aware extensions |
build.env | Record<string, string> | Build-time environment variables | All extensions |
build.dependencies | string[] | APT packages to install | puppeteerExtension, ffmpegExtension |
runtime | BuildRuntime | Node.js/Bun version | Core configuration |
contentHash | string | Deterministic build identifier | Bundler |
Sources: packages/cli-v3/src/commands/deploy.ts449-487 packages/cli-v3/src/deploy/buildImage.ts1-56
Developers can create custom extensions for project-specific requirements.
Sources: packages/build/package.json23-35
Sources: Diagram 4 (from high-level system architecture showing custom extensions with esbuild plugins)
Extensions are configured in the extensions array of the config object:
Execution Order:
onBuildStart hooks run sequentially before bundlingesbuildConfig merges cumulativelyonBuildComplete hooks run sequentially after bundlingSources: packages/cli-v3/src/commands/deploy.ts293-297
Extensions integrate with the complete deployment pipeline, from CLI to platform services.
Sources: packages/cli-v3/src/commands/deploy.ts244-563 apps/webapp/app/v3/services/initializeDeployment.server.ts20-40 apps/webapp/app/v3/services/finalizeDeploymentV2.server.ts1-10
When extensions use deploy.sync.env or deploy.sync.parentEnv, the CLI syncs these to the platform:
Sync Flow:
manifest.deploy.sync.env during onBuildCompletesyncEnvVarsWithServer() if !options.skipSyncEnvVarsEnvironmentVariableValue tableSources: packages/cli-v3/src/commands/deploy.ts449-487
Extensions modify the generated Dockerfile through the BuildManifest:
Dockerfile Generation Pseudocode:
Sources: packages/cli-v3/src/deploy/buildImage.ts58-122
Extensions should validate their configuration and fail fast with helpful messages:
Sources: packages/build/CHANGELOG.md40-50
Extensions should produce consistent results across builds:
Sources: packages/cli-v3/CHANGELOG.md14-17
Extensions can depend on other extensions by controlling array order:
Sources: packages/cli-v3/src/commands/deploy.ts293-297
Build Extensions provide a powerful, composable system for customizing Trigger.dev deployment images:
| Capability | Mechanism | Example |
|---|---|---|
| Install system packages | manifest.build.dependencies | Puppeteer, FFmpeg, Python |
| Configure runtime | manifest.build.env | Prisma engine paths |
| Sync external config | manifest.deploy.sync.env | Vercel/Neon env vars |
| Transform source code | esbuildConfig.plugins | GraphQL loader, custom transforms |
| Run build commands | Dockerfile RUN directives | prisma generate, migrations |
Key Integration Points:
Sources: packages/build/package.json1-215 packages/cli-v3/src/commands/deploy.ts1-700 packages/build/CHANGELOG.md1-500
Refresh this wiki