6.20+ beta?} Q1 -->|Yes| Modern[Modern Mode] Q1 -->|No| Q2{Using Prisma 6.16+
with engineType='client'?} Q2 -->|Yes| Modern Q2 -->|No| Q3{Need custom client
output path?} Q3 -->|Yes| Q4{Want to manage
prisma generate yourself?} Q4 -->|Yes| Engine[Engine-only Mode] Q4 -->|No| Legacy[Legacy Mode] Q3 -->|No| Legacy Modern -->|Features| ModernFeatures["• Zero configuration
• Database adapters
• Plain TypeScript (no binaries)
• You manage generation"] Engine -->|Features| EngineFeatures["• Only installs engines
• Auto version detection
• You manage generation
• Minimal overhead"] Legacy -->|Features| LegacyFeatures["• Auto prisma generate
• Migrations support
• TypedSQL support
• Config file support"] style Modern fill:#10b981,stroke:#059669,color:#fff style Engine fill:#3b82f6,stroke:#2563eb,color:#fff style Legacy fill:#8b5cf6,stroke:#7c3aed,color:#fff ``` ## Extension modes ### Legacy mode **Use when:** You're using Prisma 6.x or earlier with the `prisma-client-js` provider. **Features:** * Automatic `prisma generate` during deployment * Supports single-file schemas (`prisma/schema.prisma`) * Supports multi-file schemas (Prisma 6.7+, directory-based schemas) * Supports Prisma config files (`prisma.config.ts`) via `@prisma/config` package * Migration support with `migrate: true` * TypedSQL support with `typedSql: true` * Custom generator selection * Handles Prisma client versioning automatically (with filesystem fallback detection) * Automatic extraction of schema and migrations paths from config files **Schema configuration:** ```prisma theme={"theme":"css-variables"} generator client { provider = "prisma-client-js" previewFeatures = ["typedSql"] } datasource db { provider = "postgresql" url = env("DATABASE_URL") directUrl = env("DATABASE_URL_UNPOOLED") } ``` **Extension configuration:** ```ts theme={"theme":"css-variables"} // Single-file schema prismaExtension({ mode: "legacy", schema: "prisma/schema.prisma", migrate: true, typedSql: true, directUrlEnvVarName: "DATABASE_URL_UNPOOLED", }); // Multi-file schema (Prisma 6.7+) prismaExtension({ mode: "legacy", schema: "./prisma", // Point to directory migrate: true, typedSql: true, directUrlEnvVarName: "DATABASE_URL_UNPOOLED", }); ``` **Tested versions:** * Prisma 6.14.0 * Prisma 6.7.0+ (multi-file schema support) * Prisma 5.x *** ### Engine-only mode **Use when:** You have a custom Prisma client output path and want to manage `prisma generate` yourself. **Features:** * Only installs Prisma engine binaries (no client generation) * Automatic version detection from `@prisma/client` * Manual override of version and binary target * Minimal overhead - just ensures engines are available * You control when and how `prisma generate` runs **Schema configuration:** ```prisma theme={"theme":"css-variables"} generator client { provider = "prisma-client-js" output = "../src/generated/prisma" // Ensure the "debian-openssl-3.0.x" binary target is included for deployment to the trigger.dev cloud binaryTargets = ["native", "debian-openssl-3.0.x"] } datasource db { provider = "postgresql" url = env("DATABASE_URL") directUrl = env("DATABASE_URL_UNPOOLED") } ``` **Extension configuration:** ```ts theme={"theme":"css-variables"} // Auto-detect version prismaExtension({ mode: "engine-only", }); // Explicit version (recommended for reproducible builds) prismaExtension({ mode: "engine-only", version: "6.19.0", }); ``` **Important notes:** * You **must** run `prisma generate` yourself (typically in a prebuild script) * Your schema **must** include the correct `binaryTargets` for deployment to the trigger.dev cloud. The binary target is `debian-openssl-3.0.x`. * The extension sets `PRISMA_QUERY_ENGINE_LIBRARY` and `PRISMA_QUERY_ENGINE_SCHEMA_ENGINE` environment variables to the correct paths for the binary targets. **package.json example:** ```json theme={"theme":"css-variables"} { "scripts": { "prebuild": "prisma generate", "dev": "trigger dev", "deploy": "trigger deploy" } } ``` **Tested versions:** * Prisma 6.19.0 * Prisma 6.16.0+ *** ### Modern mode **Use when:** You're using Prisma 6.16+ with the new `prisma-client` provider (with `engineType = "client"`) or preparing for Prisma 7. **Features:** * Designed for the new Prisma architecture * Zero configuration required * Automatically marks `@prisma/client` as external * Works with Prisma 7 beta releases & Prisma 7 when released * You manage client generation (like engine-only mode) **Schema configuration (Prisma 6.16+ with engineType):** ```prisma theme={"theme":"css-variables"} generator client { provider = "prisma-client" output = "../src/generated/prisma" engineType = "client" previewFeatures = ["views"] } datasource db { provider = "postgresql" url = env("DATABASE_URL") directUrl = env("DATABASE_URL_UNPOOLED") } ``` **Schema configuration (Prisma 7):** ```prisma theme={"theme":"css-variables"} generator client { provider = "prisma-client" output = "../src/generated/prisma" } datasource db { provider = "postgresql" } ``` **Extension configuration:** ```ts theme={"theme":"css-variables"} prismaExtension({ mode: "modern", }); ``` **Prisma config (Prisma 7):** ```ts theme={"theme":"css-variables"} // prisma.config.ts import { defineConfig, env } from "prisma/config"; import "dotenv/config"; export default defineConfig({ schema: "prisma/schema.prisma", migrations: { path: "prisma/migrations", }, datasource: { url: env("DATABASE_URL"), }, }); ``` **Important notes:** * You **must** run `prisma generate` yourself. * Requires Prisma 6.16.0+ or Prisma 7 beta * The new `prisma-client` provider generates plain TypeScript (no Rust binaries) * Requires database adapters (e.g., `@prisma/adapter-pg` for PostgreSQL) **Tested versions:** * Prisma 6.16.0 with `engineType = "client"` * Prisma 6.20.0-integration-next.8 (Prisma 7 beta) *** ## Migration guide ### From old prismaExtension to legacy mode If you were using the previous `prismaExtension`, migrate to legacy mode: ```ts theme={"theme":"css-variables"} // Old prismaExtension({ schema: "prisma/schema.prisma", migrate: true, }); // New - add mode prismaExtension({ mode: "legacy", schema: "prisma/schema.prisma", migrate: true, }); ``` ### Preparing for Prisma 7 If you want to adopt the new Prisma architecture, use modern mode: 1. Update your schema to use `prisma-client` provider 2. Add database adapters to your dependencies 3. Configure the extension: ```ts theme={"theme":"css-variables"} prismaExtension({ mode: "modern", }); ``` ### Manage your own prisma generate step When using `modern` and `engine-only` modes, you'll need to ensure that you run `prisma generate` yourself before deploying your project. #### Github Actions If you are deploying your project using GitHub Actions, you can add a step to your workflow to run `prisma generate` before deploying your project, for example: ```yaml theme={"theme":"css-variables"} steps: - name: Generate Prisma client run: npx prisma@6.19.0 generate - name: Deploy Trigger.dev run: npx trigger.dev@4.1.1 deploy env: TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }} ``` #### Trigger.dev Github integration If you are using the [Trigger.dev Github integration](/github-integration), you can configure a pre-build command to run `prisma generate` before deploying your project. Navigate to your project's settings page and configure the pre-build command to run `prisma generate`, for example:
Hi {name},
{message}
Hello ${payload.name},
Welcome to Trigger.dev
`, }); if (error) { // Throwing an error will trigger a retry of this block throw error; } return data; }, { maxAttempts: 3 } ); // Then wait 3 days await wait.for({ days: 3 }); // Send the second email const secondEmailResult = await retry.onThrow( async ({ attempt }) => { const { data, error } = await resend.emails.send({ from: "hello@trigger.dev", to: payload.email, subject: "Some tips for you", html: `Hello ${payload.name},
Here are some tips for you…
`, }); if (error) { // Throwing an error will trigger a retry of this block throw error; } return data; }, { maxAttempts: 3 } ); //etc... }, }); ``` ## Testing your task To test this task in the dashboard, you can use the following payload: ```json theme={"theme":"css-variables"} { "userId": "123", "email": "{payload.title}
```mermaid theme={"theme":"css-variables"}
graph TB
A[importCSV] --> B[parseCSVFile]
B --> C[validateRows]
C --> D[bulkInsertToDB]
D --> E[notifyCompletion]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[runETLPipeline] --> B[coordinateExtraction]
B --> C[batchTriggerAndWait]
C --> D[extractFromAPI]
C --> E[extractFromDatabase]
C --> F[extractFromS3]
D --> G[transformData]
E --> G
F --> G
G --> H[validateData]
H --> I[loadToWarehouse]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[scrapeSite] --> B[coordinateScraping]
B --> C[batchTriggerAndWait]
C --> D[scrapePage1]
C --> E[scrapePage2]
C --> F[scrapePageN]
D --> G[cleanData]
E --> G
F --> G
G --> H[normalizeData]
H --> I[storeInDatabase]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[enrichRecords] --> B[fetchRecordsToEnrich]
B --> C[coordinateEnrichment]
C --> D[batchTriggerAndWait]
D --> E[enrichRecord1]
D --> F[enrichRecord2]
D --> G[enrichRecordN]
E --> H[validateEnrichedData]
F --> H
G --> H
H --> I[updateDatabase]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[userCreateAccount] --> B[sendWelcomeEmail]
B --> C[wait.for 24h]
C --> D[sendProductTipsEmail]
D --> E[wait.for 7d]
E --> F[sendFeedbackEmail]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[startCampaign] --> B[fetchUserProfile]
B --> C[selectChannel]
C --> D{Preferred
Channel?} D -->|Email| E[sendEmail1] D -->|SMS| F[sendSMS1] D -->|Push| G[sendPush1] E --> H[wait.for 2d] F --> H G --> H H --> I[sendFollowUp] I --> J[trackConversion] ```
Channel?} D -->|Email| E[sendEmail1] D -->|SMS| F[sendSMS1] D -->|Push| G[sendPush1] E --> H[wait.for 2d] F --> H G --> H H --> I[sendFollowUp] I --> J[trackConversion] ```
```mermaid theme={"theme":"css-variables"}
graph TB
A[createCampaignAssets] --> B[generateAIContent]
B --> C[wait.forToken approval]
C --> D{Approved?}
D -->|Yes| E[publishToChannels]
D -->|Needs revision| F[applyFeedback]
F --> B
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processSurveyResponse] --> B[coordinateEnrichment]
B --> C[batchTriggerAndWait]
C --> D[fetchCRMData]
C --> E[fetchAnalytics]
C --> F[fetchBehaviorData]
D --> G[analyzeAndScore]
E --> G
F --> G
G --> H[updateCRMProfile]
H --> I[triggerFollowUp]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[generateContent] --> B[createWithAI]
B --> C[wait.forToken approval]
C --> D{Approved?}
D -->|Yes| E[publishContent]
D -->|Needs revision| F[applyFeedback]
F --> B
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[generateImage] --> B[optimizeImage]
B --> C[uploadToStorage]
C --> D[updateDatabase]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processBatch] --> B[coordinateGeneration]
B --> C[batchTriggerAndWait]
C --> D[generateImage1]
C --> E[generateImage2]
C --> F[generateImageN]
D --> G[validateResults]
E --> G
F --> G
G --> H[storeResults]
H --> I[notifyCompletion]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processCreative] --> B[generateWithAI]
B --> C[applyStyleTransfer]
C --> D[upscaleResolution]
D --> E[optimizeAndCompress]
E --> F[uploadToStorage]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processVideo] --> B[downloadFromStorage]
B --> C[batchTriggerAndWait]
C --> D[transcodeToHD]
C --> E[transcodeToSD]
C --> F[extractThumbnail]
D --> G[uploadToStorage]
E --> G
F --> G
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processVideoUpload] --> B[analyzeMetadata]
B --> C{Source
Resolution?} C -->|4K Source| D[transcode4K] C -->|HD Source| E[transcodeHD] C -->|SD Source| F[transcodeSD] D --> G[coordinatePostProcessing] E --> G F --> G G --> H[batchTriggerAndWait] H --> I[extractThumbnails] H --> J[generatePreview] H --> K[detectChapters] I --> L[uploadToStorage] J --> L K --> L L --> M[notifyComplete] ```
Resolution?} C -->|4K Source| D[transcode4K] C -->|HD Source| E[transcodeHD] C -->|SD Source| F[transcodeSD] D --> G[coordinatePostProcessing] E --> G F --> G G --> H[batchTriggerAndWait] H --> I[extractThumbnails] H --> J[generatePreview] H --> K[detectChapters] I --> L[uploadToStorage] J --> L K --> L L --> M[notifyComplete] ```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processImageUpload] --> B[analyzeContent]
B --> C{Content
Type?} C -->|Product| D[removeBackground] C -->|Portrait| E[detectFaces] C -->|Landscape| F[analyzeScene] D --> G[upscaleWithAI] E --> G F --> G G --> H[batchTriggerAndWait] H --> I[generateWebP] H --> J[generateThumbnails] H --> K[generateSocialCrops] I --> L[uploadToStorage] J --> L K --> L ```
Type?} C -->|Product| D[removeBackground] C -->|Portrait| E[detectFaces] C -->|Landscape| F[analyzeScene] D --> G[upscaleWithAI] E --> G F --> G G --> H[batchTriggerAndWait] H --> I[generateWebP] H --> J[generateThumbnails] H --> K[generateSocialCrops] I --> L[uploadToStorage] J --> L K --> L ```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processAudioUpload] --> B[cleanAudio]
B --> C[coordinateProcessing]
C --> D[batchTriggerAndWait]
D --> E[transcribeWithDeepgram]
D --> F[enhanceAudio]
D --> G[detectChapters]
E --> H[generateShowNotes]
F --> H
G --> H
H --> I[publishToPlatforms]
```
```mermaid theme={"theme":"css-variables"}
graph TB
A[processDocumentUpload] --> B[detectFileType]
B -->|PDF| C[extractText]
B -->|Word/Excel| D[convertToPDF]
B -->|Image| E[runOCR]
C --> F[classifyDocument]
D --> F
E --> F
F -->|Invoice| G[extractLineItems]
F -->|Contract| H[extractClauses]
F -->|Receipt| I[extractExpenses]
G --> J{Needs
Review?} H --> J I --> J J -->|Yes| K[wait.forToken approval] J -->|No| L[processAndIntegrate] K --> L ```
Review?} H --> J I --> J J -->|Yes| K[wait.forToken approval] J -->|No| L[processAndIntegrate] K --> L ```
Error: {error.message}
;
if (!run) return Loading...
;
return (
Status: {run.status}
Progress: {run.completedAt ? "Complete" : "Running..."}
Error: {error.message}
;
if (!parts) return Loading...
;
return (
{parts.map((part, i) => (
{part}
))}
);
}
```
### With Defined Streams
The recommended approach is to use defined streams for full type safety:
```tsx theme={"theme":"css-variables"}
"use client";
import { useRealtimeStream } from "@trigger.dev/react-hooks";
import { aiStream } from "@/app/streams";
export function StreamViewer({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
// Pass the defined stream directly - full type safety!
const { parts, error } = useRealtimeStream(aiStream, runId, {
accessToken: publicAccessToken,
timeoutInSeconds: 600,
onData: (chunk) => {
console.log("New chunk:", chunk); // chunk is typed!
},
});
if (error) return Error: {error.message}
;
if (!parts) return Loading...
;
return (
{parts.map((part, i) => (
{part}
))}
);
}
```
### Streaming AI Responses
Here's a complete example showing how to display streaming AI responses:
```tsx theme={"theme":"css-variables"}
"use client";
import { useRealtimeStream } from "@trigger.dev/react-hooks";
import { aiStream } from "@/trigger/streams";
import { Streamdown } from "streamdown";
export function AIStreamViewer({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
const { parts, error } = useRealtimeStream(aiStream, runId, {
accessToken: publicAccessToken,
timeoutInSeconds: 300,
});
if (error) return Error: {error.message}
;
if (!parts) return Loading stream...
;
const text = parts.join("");
return (
Error: {error.message}
;
return (
Run: {run.id}
{Object.keys(streams).map((stream) => (
Stream: {stream}
))}
Error: {error.message}
;
const text = streams.openai?.map((part) => part).join("");
return (
Run: {run.id}
{text}
Error: {error.message}
;
const text = streams.openai
?.filter((stream) => stream.type === "text-delta")
?.map((part) => part.text)
.join("");
return (
Run: {run.id}
{text}
Loading...
;
}
const text = streams.openai.join(""); // `streams.openai` is an array of strings
return (
OpenAI response:
{text}
Loading...
;
}
// streams.openai is an array of TextStreamPart
const toolCall = streams.openai.find(
(stream) => stream.type === "tool-call" && stream.toolName === "getWeather"
);
const toolResult = streams.openai.find((stream) => stream.type === "tool-result");
const textDeltas = streams.openai.filter((stream) => stream.type === "text-delta");
const text = textDeltas.map((delta) => delta.textDelta).join("");
const weatherLocation = toolCall ? toolCall.args.location : undefined;
const weather = toolResult ? toolResult.result.temperature : undefined;
return (
OpenAI response:
{text}
Weather:
{weatherLocation ? `The weather in ${weatherLocation} is ${weather} degrees.` : "No weather data"}
Error: {error.message}
;
return (
Run: {run.id}
{/* Display streams */}
Error: {error.message}
;
return Run: {run.id}
;
}
```
To correctly type the run's payload and output, you can provide the type of your task to the `useRealtimeRun` hook:
```tsx theme={"theme":"css-variables"}
import { useRealtimeRun } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";
export function MyComponent({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
const { run, error } = useRealtimeRunError: {error.message}
;
// Now run.payload and run.output are correctly typed
return Run: {run.id}
;
}
```
You can supply an `onComplete` callback to the `useRealtimeRun` hook to be called when the run is completed or errored. This is useful if you want to perform some action when the run is completed, like navigating to a different page or showing a notification.
```tsx theme={"theme":"css-variables"}
import { useRealtimeRun } from "@trigger.dev/react-hooks";
export function MyComponent({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
const { run, error } = useRealtimeRun(runId, {
accessToken: publicAccessToken,
onComplete: (run, error) => {
console.log("Run completed", run);
},
});
if (error) return Error: {error.message}
;
return Run: {run.id}
;
}
```
When you only need run status (for example, a progress bar or completion badge), you can omit large fields like `payload` and `output` by passing `skipColumns`. This reduces the data sent over the wire and avoids issues such as "Large HTTP Payload" warnings in tools like Sentry.
```tsx theme={"theme":"css-variables"}
import { useRealtimeRun } from "@trigger.dev/react-hooks";
export function RunStatusBadge({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
const { run, error } = useRealtimeRun(runId, {
accessToken: publicAccessToken,
skipColumns: ["payload", "output"],
});
if (error) return Error;
if (!run) return Loading…;
return Status: {run.status};
}
```
You can skip any of: `payload`, `output`, `metadata`, `startedAt`, `delayUntil`, `queuedAt`, `expiredAt`, `completedAt`, `number`, `isTest`, `usageDurationMs`, `costInCents`, `baseCostInCents`, `ttl`, `payloadType`, `outputType`, `runTags`, `error`. The `useRealtimeRunsWithTag` hook also accepts a `skipColumns` option in the same way.
See our [run object reference](/realtime/run-object) for the complete schema and [How it Works documentation](/realtime/how-it-works) for more technical details.
### useRealtimeRunsWithTag
The `useRealtimeRunsWithTag` hook allows you to subscribe to multiple runs with a specific tag.
```tsx theme={"theme":"css-variables"}
"use client"; // This is needed for Next.js App Router or other RSC frameworks
import { useRealtimeRunsWithTag } from "@trigger.dev/react-hooks";
export function MyComponent({ tag }: { tag: string }) {
const { runs, error } = useRealtimeRunsWithTag(tag);
if (error) return Error: {error.message}
;
return (
{runs.map((run) => (
);
}
```
To correctly type the runs payload and output, you can provide the type of your task to the `useRealtimeRunsWithTag` hook:
```tsx theme={"theme":"css-variables"}
import { useRealtimeRunsWithTag } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";
export function MyComponent({ tag }: { tag: string }) {
const { runs, error } = useRealtimeRunsWithTagRun: {run.id}
))}
Error: {error.message}
;
// Now runs[i].payload and runs[i].output are correctly typed
return (
{runs.map((run) => (
);
}
```
If `useRealtimeRunsWithTag` could return multiple different types of tasks, you can pass a union of all the task types to the hook:
```tsx theme={"theme":"css-variables"}
import { useRealtimeRunsWithTag } from "@trigger.dev/react-hooks";
import type { myTask1, myTask2 } from "@/trigger/myTasks";
export function MyComponent({ tag }: { tag: string }) {
const { runs, error } = useRealtimeRunsWithTagRun: {run.id}
))}
Error: {error.message}
;
// You can narrow down the type of the run based on the taskIdentifier
for (const run of runs) {
if (run.taskIdentifier === "my-task-1") {
// run is correctly typed as myTask1
} else if (run.taskIdentifier === "my-task-2") {
// run is correctly typed as myTask2
}
}
return (
{runs.map((run) => (
);
}
```
### useRealtimeBatch
The `useRealtimeBatch` hook allows you to subscribe to a batch of runs by its the batch ID.
```tsx theme={"theme":"css-variables"}
"use client"; // This is needed for Next.js App Router or other RSC frameworks
import { useRealtimeBatch } from "@trigger.dev/react-hooks";
export function MyComponent({ batchId }: { batchId: string }) {
const { runs, error } = useRealtimeBatch(batchId);
if (error) return Run: {run.id}
))}
Error: {error.message}
;
return (
{runs.map((run) => (
);
}
```
See our [Realtime documentation](/realtime) for more information.
## Using metadata to show progress in your UI
All realtime hooks automatically include metadata updates. Whenever your task updates metadata using `metadata.set()`, `metadata.append()`, or other metadata methods, your component will re-render with the updated data.
Run: {run.id}
))}
Loading run...
;
if (error) return Error: {error.message}
;
if (!run) return Run not found
;
const progress = run.metadata?.progress as
| {
current: number;
total: number;
percentage: number;
currentItem: string;
}
| undefined;
return (
Run Status: {run.status}
Run ID: {run.id}
Progress
{progress.percentage}%
Processing: {progress.currentItem} ({progress.current}/{progress.total})
{title &&
);
}
```
### Status indicator with logs
This example demonstrates how to create a status indicator component that can be used to display the status of a run, and also logs that are emitted by the task:
```tsx theme={"theme":"css-variables"}
"use client";
import { useRealtimeRun } from "@trigger.dev/react-hooks";
interface StatusIndicatorProps {
runId: string;
publicAccessToken: string;
}
export function StatusIndicator({ runId, publicAccessToken }: StatusIndicatorProps) {
const { run } = useRealtimeRun(runId, {
accessToken: publicAccessToken,
});
const status = run?.metadata?.status as string | undefined;
const logs = run?.metadata?.logs as string[] | undefined;
const getStatusColor = (status: string | undefined) => {
switch (status) {
case "completed":
return "text-green-600 bg-green-100";
case "failed":
return "text-red-600 bg-red-100";
case "running":
return "text-blue-600 bg-blue-100";
default:
return "text-gray-600 bg-gray-100";
}
};
return (
{title}
}
{progress?.current && progress?.total
? `${progress.current}/${progress.total} items`
: "Processing..."}
{percentage}%
{progress?.currentItem && (
Current: {progress.currentItem}
)}
{status || run?.status || "Unknown"}
Run {run?.id}
{logs && logs.length > 0 && (
Logs
{logs.map((log, index) => (
{log}
))}
Deployment Progress
{/* Stage indicators */}
{DEPLOYMENT_STAGES.map((stage, index) => {
const isActive = currentStageIndex === index;
const isCompleted = currentStageIndex > index;
const isFailed = run?.status === "FAILED" && currentStageIndex === index;
return (
);
})}
{/* Recent logs */}
{logs && logs.length > 0 && (
{isCompleted ? "✓" : index + 1}
{stage}
{isActive && (
)}
{logs.slice(-5).map((log, index) => (
$
{log}
))}
{metadata?.progress &&
);
}
```
## Common options
### accessToken & baseURL
You can pass the `accessToken` option to the Realtime hooks to authenticate the subscription.
```tsx theme={"theme":"css-variables"}
import { useRealtimeRun } from "@trigger.dev/react-hooks";
export function MyComponent({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
const { run, error } = useRealtimeRun(runId, {
accessToken: publicAccessToken,
baseURL: "https://my-self-hosted-trigger.com", // Optional if you are using a self-hosted Trigger.dev instance
});
if (error) return Progress: {metadata.progress.percentage}%
} {metadata?.user && (User: {metadata.user.name} ({metadata.user.id})
)} {metadata?.status &&Status: {metadata.status}
}Error: {error.message}
;
return Run: {run.id}
;
}
```
### enabled
You can pass the `enabled` option to the Realtime hooks to enable or disable the subscription.
```tsx theme={"theme":"css-variables"}
import { useRealtimeRun } from "@trigger.dev/react-hooks";
export function MyComponent({
runId,
publicAccessToken,
enabled,
}: {
runId: string;
publicAccessToken: string;
enabled: boolean;
}) {
const { run, error } = useRealtimeRun(runId, {
accessToken: publicAccessToken,
enabled,
});
if (error) return Error: {error.message}
;
return Run: {run.id}
;
}
```
This allows you to conditionally disable using the hook based on some state.
### id
You can pass the `id` option to the Realtime hooks to change the ID of the subscription.
```tsx theme={"theme":"css-variables"}
import { useRealtimeRun } from "@trigger.dev/react-hooks";
export function MyComponent({
id,
runId,
publicAccessToken,
enabled,
}: {
id: string;
runId: string;
publicAccessToken: string;
enabled: boolean;
}) {
const { run, error } = useRealtimeRun(runId, {
accessToken: publicAccessToken,
enabled,
id,
});
if (error) return Error: {error.message}
;
return Run: {run.id}
;
}
```
This allows you to change the ID of the subscription based on some state. Passing in a different ID will unsubscribe from the current subscription and subscribe to the new one (and remove any cached data).
# SWR hooks
Source: https://trigger.dev/docs/realtime/react-hooks/swr
Fetch and cache data using SWR-based hooks
SWR hooks use the [swr](https://swr.vercel.app/) library to fetch data once and cache it. These hooks are useful when you need to fetch data without real-time updates.
Loading...
;
if (error) return Error: {error.message}
;
return Run: {run.id}
;
}
```
The `run` object returned is the same as the [run object](/management/runs/retrieve) returned by the Trigger.dev API. To correctly type the run's payload and output, you can provide the type of your task to the `useRun` hook:
```tsx theme={"theme":"css-variables"}
import { useRun } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";
export function MyComponent({ runId }: { runId: string }) {
const { run, error, isLoading } = useRunLoading...
;
if (error) return Error: {error.message}
;
// Now run.payload and run.output are correctly typed
return Run: {run.id}
;
}
```
## Common SWR options
You can pass the following options to the all SWR hooks:
Error: {error.message}
;
}
if (handle) {
return Run ID: {handle.id}
;
}
return (
);
}
```
`useTaskTrigger` returns an object with the following properties:
* `submit`: A function that triggers the task. It takes the payload of the task as an argument.
* `handle`: The run handle object. This object contains the ID of the run that was triggered, along with a Public Access Token that can be used to access the run.
* `isLoading`: A boolean that indicates whether the task is currently being triggered.
* `error`: An error object that contains any errors that occurred while triggering the task.
The `submit` function triggers the task with the specified payload. You can additionally pass an optional [options](/triggering#options) argument to the `submit` function:
```tsx theme={"theme":"css-variables"}
submit({ foo: "bar" }, { tags: ["tag1", "tag2"] });
```
#### Using the handle object
You can use the `handle` object to initiate a subsequent [Realtime hook](/realtime/react-hooks/subscribe#userealtimerun) to subscribe to the run.
```tsx theme={"theme":"css-variables"}
"use client"; // This is needed for Next.js App Router or other RSC frameworks
import { useTaskTrigger, useRealtimeRun } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";
// 👆 This is the type of your task
export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
// pass the type of your task here 👇
const { submit, handle, error, isLoading } = useTaskTriggerError: {error.message}
;
}
if (handle) {
return Run ID: {handle.id}
;
}
if (realtimeError) {
return Error: {realtimeError.message}
;
}
if (run) {
return Run ID: {run.id}
;
}
return (
);
}
```
We've also created some additional hooks that allow you to trigger tasks and subscribe to the run in one step:
### useRealtimeTaskTrigger
The `useRealtimeTaskTrigger` hook allows you to trigger a task from your frontend application and then subscribe to the run in using Realtime:
```tsx theme={"theme":"css-variables"}
"use client"; // This is needed for Next.js App Router or other RSC frameworks
import { useRealtimeTaskTrigger } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";
export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
const { submit, run, error, isLoading } = useRealtimeTaskTriggerError: {error.message}
;
}
// This is the Realtime run object, which will automatically update when the run changes
if (run) {
return Run ID: {run.id}
;
}
return (
);
}
```
### useRealtimeTaskTriggerWithStreams
The `useRealtimeTaskTriggerWithStreams` hook allows you to trigger a task from your frontend application and then subscribe to the run in using Realtime, and also receive any streams that are emitted by the task.
```tsx theme={"theme":"css-variables"}
"use client"; // This is needed for Next.js App Router or other RSC frameworks
import { useRealtimeTaskTriggerWithStreams } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";
type STREAMS = {
openai: string; // this is the type of each "part" of the stream
};
export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
const { submit, run, streams, error, isLoading } = useRealtimeTaskTriggerWithStreams<
typeof myTask,
STREAMS
>("my-task", {
accessToken: publicAccessToken,
});
if (error) {
return Error: {error.message}
;
}
if (streams && run) {
const text = streams.openai?.map((part) => part).join("");
return (
Run ID: {run.id}
{text}
Error: {error.message}
;
if (!parts) return Loading...
;
return (
{parts.map((part, i) => (
{part}
))}
);
}
```
## Direct Stream Methods (Without Defining)
Error: {error.message}
;
if (!parts) return Loading...
;
return (
{parts.map((part, i) => (
{part}
))}
);
}
```
### With Direct Stream Keys
If you prefer not to use defined streams, you can specify the stream key directly:
```tsx theme={"theme":"css-variables"}
"use client";
import { useRealtimeStream } from "@trigger.dev/react-hooks";
export function StreamViewer({ accessToken, runId }: { accessToken: string; runId: string }) {
const { parts, error } = useRealtimeStreamError: {error.message}
;
if (!parts) return Loading...
;
return (
{parts.map((part, i) => (
{part}
))}
);
}
```
### Using Default Stream
```tsx theme={"theme":"css-variables"}
// Omit stream key to use the default stream
const { parts, error } = useRealtimeStreamError: {error.message}
;
if (!parts) return Loading...
;
return (
{parts.map((part, i) => (
{part}
))}
);
}
```
## Migration from v1
If you're using the old `metadata.stream()` API, here's how to migrate to the recommended v2 approach:
### Step 1: Define Your Streams
Create a shared streams definition file:
```ts theme={"theme":"css-variables"}
// app/streams.ts or trigger/streams.ts
import { streams, InferStreamType } from "@trigger.dev/sdk";
export const myStream = streams.defineHello ${payload.name},
...
`, }); }, }); ``` This allows you to write linear code without having to worry about the complexity of scheduling or managing cron jobs. In the Trigger.dev Cloud we automatically pause execution of tasks when they are waiting for longer than a few seconds. When triggering and waiting for subtasks, the parent is checkpointed and while waiting does not count towards compute usage. When waiting for a time period (`wait.for` or `wait.until`), if the wait is longer than 5 seconds we checkpoint and it does not count towards compute usage. ## `throwIfInThePast` You can optionally throw an error if the date is already in the past when the function is called: ```ts theme={"theme":"css-variables"} await wait.until({ date: new Date(date), throwIfInThePast: true }); ``` You can of course use try/catch if you want to do something special in this case. ## Wait idempotency You can pass an idempotency key to any wait function, allowing you to skip waits if the same idempotency key is used again. This can be useful if you want to skip waits when retrying a task, for example: ```ts theme={"theme":"css-variables"} // Specify the idempotency key and TTL when waiting until a date: await wait.until({ date: futureDate, idempotencyKey: "my-idempotency-key", idempotencyKeyTTL: "1h", }); ``` # Writing tasks: Overview Source: https://trigger.dev/docs/writing-tasks-introduction Tasks are the core of Trigger.dev. They are long-running processes that are triggered by events. Before digging deeper into the details of writing tasks, you should read the [fundamentals of tasks](/tasks/overview) to understand what tasks are and how they work. ## Writing tasks | Topic | Description | | :------------------------------------------- | :-------------------------------------------------------------------------------------------------- | | [Logging](/logging) | View and send logs and traces from your tasks. | | [Errors & retrying](/errors-retrying) | How to deal with errors and write reliable tasks. | | [Wait](/wait) | Wait for periods of time or for external events to occur before continuing. | | [Concurrency & Queues](/queue-concurrency) | Configure what you want to happen when there is more than one run at a time. | | [Realtime notifications](/realtime/overview) | Send realtime notifications from your task that you can subscribe to from your backend or frontend. | | [Versioning](/versioning) | How versioning works. | | [Machines](/machines) | Configure the CPU and RAM of the machine your task runs on | | [Idempotency](/idempotency) | Protect against mutations happening twice. | | [Replaying](/replaying) | You can replay a single task or many at once with a new version of your code. | | [Max duration](/runs/max-duration) | Set a maximum duration for your task to run. | | [Tags](/tags) | Tags allow you to easily filter runs in the dashboard and when using the SDK. | | [Metadata](/runs/metadata) | Attach a small amount of data to a run and update it as the run progresses. | | [Usage](/run-usage) | Get compute duration and cost from inside a run, or for a specific block of code. | | [Context](/context) | Access the context of the task run. | | [Bulk actions](/bulk-actions) | Run actions on many task runs at once. | | [Priority](/runs/priority) | Specify a priority when triggering a task. | | [Hidden tasks](/hidden-tasks) | Create tasks that are not exported from your trigger files but can still be executed. | ## Our library of examples, guides and projects