Integration Patterns

Relevant source files

Purpose and Scope

This page documents common integration patterns used when building tasks with Trigger.dev, as demonstrated throughout the documentation examples and use case guides. These patterns represent proven approaches for orchestrating workflows across external services, processing pipelines, and system integrations.

For information about the SDK's task definition and triggering APIs, see Task Definition API and Task Triggering and Scheduling. For build-time integrations and runtime customizations, see Build Extensions. For production examples and detailed implementations, see Example Projects and Tasks.

Common Workflow Orchestration Patterns

Integration patterns in Trigger.dev leverage core SDK features to coordinate work across multiple systems. These patterns appear repeatedly across different use cases with similar structural characteristics.

Router Pattern

The Router pattern analyzes input or intermediate state to determine which specialized processing path to follow. A parent task examines the payload and conditionally triggers different child tasks based on classification logic.

Key characteristics:

Single entry point task that classifies or routes work
Conditional logic determines which downstream task(s) to trigger
Each branch handles a specific type of processing
Often combined with task.trigger() or task.triggerAndWait() for orchestration

Diagram: Router Pattern Structure

Sources: docs/guides/use-cases/media-processing.mdx69-98 docs/guides/use-cases/media-generation.mdx100-141 docs/guides/use-cases/marketing.mdx76-100

Coordinator Pattern

The Coordinator pattern manages parallel execution of multiple child tasks and aggregates their results. The parent task uses batchTriggerAndWait() to fan out work to child tasks, waits for all to complete, then processes the combined output.

Key characteristics:

Parent task coordinates multiple parallel child tasks
Uses task.batchTriggerAndWait() for concurrent execution
Configurable concurrency limits via queue settings
Results aggregated after all children complete

Diagram: Coordinator Pattern with Batch Triggering

Example implementation from Hacker News scraper:

Sources: docs/guides/examples/scrape-hacker-news.mdx129-136 docs/guides/use-cases/data-processing-etl.mdx83-105 docs/guides/use-cases/media-generation.mdx100-122

Supervisor Pattern with Approval Gate

The Supervisor pattern implements human-in-the-loop workflows by pausing execution with wait.forToken() to enable manual review and approval before proceeding.

Key characteristics:

Task execution pauses at approval checkpoint
Uses wait.forToken() to create waitpoint token
External approval process completes the token
Conditional logic handles approval vs. rejection paths
May loop back to regenerate on rejection

Diagram: Supervisor Pattern with Human Review

Sources: docs/guides/use-cases/media-generation.mdx67-84 docs/guides/use-cases/marketing.mdx102-119 docs/guides/use-cases/media-processing.mdx157-188

Sequential Pipeline Pattern

The Sequential Pipeline pattern chains multiple processing stages where each stage's output becomes the next stage's input. Common in ETL and media processing workflows.

Key characteristics:

Linear sequence of transformations
Each step depends on previous step's output
May include wait.for() delays between stages
Output progressively transformed through pipeline

Diagram: Sequential Pipeline

Sources: docs/guides/use-cases/data-processing-etl.mdx69-80 docs/guides/use-cases/media-generation.mdx126-140

Integration Pattern Categories

The documentation examples demonstrate integration patterns organized by use case domains. Each category leverages the core orchestration patterns while integrating with domain-specific external services.

AI Agent Integration Patterns

AI agent integrations coordinate LLM calls, tool execution, and multi-agent workflows. These patterns handle unpredictable API latencies and complex orchestration requirements.

Documented examples:

Example	Pattern	Description	Documentation Reference
OpenAI Agents SDK Playground	Router + Coordinator	Multiple agent types with tool calling and handoffs	docs/guides/example-projects/openai-agents-sdk-typescript-playground.mdx
OpenAI Agents SDK Guardrails	Supervisor	Input/output guardrails with exception handling	docs/guides/example-projects/openai-agent-sdk-guardrails.mdx
Content Moderation	Coordinator	Parallel content checks while responding	docs/guides/introduction.mdx26
Route Questions	Router	Complexity-based model routing	docs/guides/introduction.mdx29
Translation Refinement	Sequential + Supervisor	Iterative translation with feedback	docs/guides/introduction.mdx30

Common SDK features used:

task.trigger() for agent invocation
task.batchTriggerAndWait() for parallel agent processing
logger.info() for agent state tracking
wait.forToken() for human verification
Error handling with retry configuration

Diagram: Multi-Agent Coordinator Pattern

Sources: docs/guides/example-projects/openai-agents-sdk-typescript-playground.mdx40-48 docs/guides/introduction.mdx24-42

Media Processing Integration Patterns

Media processing integrations handle video transcoding, image optimization, audio transformation, and document conversion. These patterns process large files and long-running operations.

Documented examples:

Example	Pattern	External Services	Documentation Reference
FFmpeg Video Processing	Sequential	FFmpeg, Cloudflare R2	docs/guides/examples/ffmpeg-video-processing.mdx
Product Image Generator	Router + Coordinator	Replicate	docs/guides/example-projects/product-image-generator.mdx
LibreOffice PDF Conversion	Sequential	LibreOffice	docs/guides/examples/libreoffice-pdf-conversion.mdx
Sharp Image Processing	Sequential	Sharp, Cloudflare R2	docs/guides/examples/sharp-image-processing.mdx
PDF to Image	Sequential	MuPDF, Cloudflare R2	docs/guides/examples/pdf-to-image.mdx

Build extensions commonly used:

ffmpeg() for video processing docs/introduction.mdx99
puppeteer() for browser automation docs/introduction.mdx97
playwright() for headless browsers docs/introduction.mdx96
aptGet() for system packages docs/introduction.mdx100

Diagram: Adaptive Video Processing with Router Pattern

Sources: docs/guides/use-cases/media-processing.mdx44-98 docs/introduction.mdx92-107

AI Media Generation Integration Patterns

AI media generation integrations coordinate image generation, video synthesis, and audio creation through AI model APIs. These patterns handle unpredictable generation times and implement quality gates.

Documented examples:

Example	Pattern	AI Service	Documentation Reference
Fal.ai Image Generation (Realtime)	Sequential	Fal.ai	docs/guides/examples/fal-ai-realtime.mdx
Fal.ai Image to Cartoon	Sequential	Fal.ai	docs/guides/examples/fal-ai-image-to-cartoon.mdx
DALL·E 3 Image Generation	Sequential	OpenAI	docs/guides/examples/dall-e3-generate-image.mdx
Replicate Image Generation	Sequential	Replicate	docs/guides/examples/replicate-image-generation.mdx
Meme Generator	Supervisor	OpenAI DALL·E 3	docs/guides/example-projects/meme-generator-human-in-the-loop.mdx
Vercel AI SDK Image Generator	Sequential	Vercel AI SDK	docs/guides/example-projects/vercel-ai-sdk-image-generator.mdx

Fal.ai integration example:

Diagram: AI Generation with Approval Gate

Sources: docs/guides/examples/fal-ai-realtime.mdx42-78 docs/guides/examples/fal-ai-image-to-cartoon.mdx59-101 docs/guides/use-cases/media-generation.mdx64-143

Data Pipeline Integration Patterns

Data pipeline integrations implement ETL workflows, web scraping, database synchronization, and batch enrichment operations. These patterns process large datasets without timeout constraints.

Documented examples:

Example	Pattern	Data Source/Sink	Documentation Reference
Realtime CSV Importer	Sequential	CSV files	docs/guides/example-projects/realtime-csv-importer.mdx
Hacker News Scraper	Coordinator	BrowserBase, Puppeteer	docs/guides/examples/scrape-hacker-news.mdx
Supabase Database Webhooks	Sequential	Supabase	docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx
Sequin Database Triggers	Sequential	Sequin, PostgreSQL	docs/guides/frameworks/sequin.mdx
Python Web Crawler	Coordinator	Crawl4AI, Playwright	docs/guides/python/python-crawl4ai.mdx

Scraping pattern with proxy (required for compliance):

The Hacker News scraper demonstrates the Coordinator pattern with BrowserBase proxy integration (required by terms of service):

Diagram: Parallel Web Scraping with Coordinator

Sources: docs/guides/examples/scrape-hacker-news.mdx80-210 docs/guides/use-cases/data-processing-etl.mdx64-156 docs/snippets/web-scraping-warning.mdx1-3

Marketing Automation Integration Patterns

Marketing automation integrations implement drip campaigns, behavioral triggers, personalization engines, and multi-channel orchestration. These patterns use delays and conditional branching extensively.

Documented examples:

Example	Pattern	Services	Documentation Reference
Resend Email Sequence	Sequential with Delays	Resend	docs/guides/examples/resend-email-sequence.mdx
React Email	Sequential	React Email	docs/guides/examples/react-email.mdx
Stripe Webhooks	Router	Stripe, webhooks	docs/guides/examples/stripe-webhook.mdx

Key features for marketing workflows:

wait.for({ days: 7 }) for drip campaign delays over 5 seconds (automatically checkpointed)
schedules.task() for recurring campaigns
idempotencyKey to prevent duplicate sends
task.triggerAndWait() for conditional follow-up logic

Diagram: Multi-Channel Drip Campaign with Router

Sources: docs/guides/use-cases/marketing.mdx56-145 docs/guides/introduction.mdx86

Webhook Integration Patterns

Webhook integrations receive external events and trigger task execution. These patterns validate incoming payloads, implement idempotency, and route to appropriate handlers.

Documented examples:

Example	Framework	Webhook Source	Documentation Reference
Stripe Webhooks	Multiple	Stripe	docs/guides/examples/stripe-webhook.mdx
Next.js Webhooks	Next.js	Generic	docs/guides/frameworks/nextjs-webhooks.mdx
Remix Webhooks	Remix	Generic	docs/guides/frameworks/remix-webhooks.mdx
Supabase Database Webhooks	Supabase Edge Functions	Supabase	docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx

Common webhook handler pattern:

Diagram: Webhook Router Pattern

Sources: docs/guides/introduction.mdx38-42 docs/docs.json366-377

Database Integration Patterns

Database integrations sync data, trigger tasks from database changes, and implement transaction-safe workflows. These patterns often use build extensions for database clients.

Documented examples:

Example	Database	Integration Type	Documentation Reference
Prisma	PostgreSQL/MySQL	ORM	docs/guides/frameworks/prisma.mdx
Supabase Operations	PostgreSQL	Supabase Client	docs/guides/examples/supabase-database-operations.mdx
Sequin Database Triggers	PostgreSQL	CDC Streaming	docs/guides/frameworks/sequin.mdx
Drizzle	PostgreSQL/MySQL	ORM	docs/guides/frameworks/drizzle.mdx
Turborepo with Prisma	PostgreSQL	Monorepo	docs/guides/example-projects/turborepo-monorepo-prisma.mdx

Build extension for Prisma:

Diagram: Database Change Trigger Pattern

Sources: docs/guides/introduction.mdx32 docs/introduction.mdx94 docs/guides/introduction.mdx37

Pattern Implementation Features

The SDK provides specific features that enable these integration patterns. Understanding how patterns map to SDK capabilities helps implement robust integrations.

Orchestration Features

SDK Feature	Pattern Enablement	Common Use Cases
`task.trigger()`	Router, Sequential	Fire-and-forget task invocation
`task.triggerAndWait()`	Router, Sequential	Wait for child task completion
`task.batchTrigger()`	Coordinator	Parallel tasks without waiting
`task.batchTriggerAndWait()`	Coordinator	Fan-out with result aggregation
`schedules.task()`	All patterns	Recurring workflow execution
`wait.for()`	Sequential	Delays between pipeline stages
`wait.forToken()`	Supervisor	Human-in-the-loop approval

Sources: docs/introduction.mdx39-41 docs/introduction.mdx49-82

Reliability Features

SDK Feature	Purpose	Implementation Location
`idempotencyKey`	Prevent duplicate execution	Trigger options parameter
`retry` configuration	Automatic failure recovery	Task definition options
`queue` configuration	Concurrency control	Task definition options
Checkpoint/resume	Long-running task efficiency	Automatic for waits > 5s
Heartbeat tracking	Zombie process detection	Automatic in task execution

Sources: docs/introduction.mdx66-73 docs/guides/examples/scrape-hacker-news.mdx32

Monitoring Features

SDK Feature	Purpose	Integration Pattern Usage
`logger.info()`	Structured logging	All patterns for progress tracking
`logger.error()`	Error reporting	Error boundaries in all patterns
`context.run.id`	Run identification	Correlation across distributed tasks
`context.metadata`	Custom metadata	Progress tracking in UI
Realtime API	Live status updates	User-facing progress indicators

Sources: docs/introduction.mdx57-59 docs/video-walkthrough.mdx22

Build Extensions for Integration

Build extensions enable integration with external tools and services by modifying the runtime environment:

Extension	Integration Support	Documentation
`prismaExtension`	Database ORM integration	docs/introduction.mdx94
`pythonExtension`	Python script execution	docs/introduction.mdx95
`puppeteer`	Headless browser automation	docs/introduction.mdx97
`playwright`	Browser testing/scraping	docs/introduction.mdx96
`ffmpeg`	Video/audio processing	docs/introduction.mdx99
`aptGet`	System package installation	docs/introduction.mdx100

Sources: docs/introduction.mdx90-107 docs/guides/examples/scrape-hacker-news.mdx52-64

Pattern Selection Guidelines

Choosing the appropriate integration pattern depends on workflow characteristics:

Use Router Pattern when:

Input requires classification before processing
Different processing logic needed for different input types
Conditional branching based on business rules
Example: Route support tickets by priority/category

Use Coordinator Pattern when:

Multiple independent operations can run in parallel
Results need aggregation after parallel processing
Rate limiting or concurrency control required
Example: Batch process uploaded files, enrich database records

Use Supervisor Pattern when:

Human approval required before proceeding
Quality gates for AI-generated content
Compliance review needed
Example: Content moderation, expense approval

Use Sequential Pipeline when:

Each stage depends on previous stage output
Linear transformation workflow
State must progress through ordered stages
Example: ETL pipeline, media transcoding

Combining patterns:

Router → Coordinator: Route to different batch processors
Coordinator → Sequential: Parallel processing with sequential post-processing
Sequential → Supervisor: Process then await approval before publishing
All patterns can nest additional child patterns

Sources: docs/guides/use-cases/media-processing.mdx44-189 docs/guides/use-cases/data-processing-etl.mdx64-158 docs/guides/use-cases/media-generation.mdx64-143 docs/guides/use-cases/marketing.mdx56-145

Integration Patterns

Purpose and Scope

Common Workflow Orchestration Patterns

Router Pattern

Coordinator Pattern

Supervisor Pattern with Approval Gate

Sequential Pipeline Pattern

Integration Pattern Categories

AI Agent Integration Patterns

Media Processing Integration Patterns

AI Media Generation Integration Patterns

Data Pipeline Integration Patterns

Marketing Automation Integration Patterns

Webhook Integration Patterns

Database Integration Patterns

Pattern Implementation Features

Orchestration Features

Reliability Features

Monitoring Features

Build Extensions for Integration

Pattern Selection Guidelines

On this page