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).
## Frequently asked questions
### How do I show a progress bar for a background task in React?
Use `metadata.set()` inside your task to update a progress value, then read it with `useRealtimeRun` in your component. The hook re-renders your component on every metadata change. See [Using metadata to show progress](#using-metadata-to-show-progress-in-your-ui) above for a complete example.
### What's the difference between run updates and streaming?
Run updates (this page) give you **run state**: status, metadata, and tags. They're for progress bars, status badges, and dashboards. [Streaming](/realtime/react-hooks/streams) gives you **continuous data** like AI tokens or file chunks. Use run updates for "how far along is my task?" and streaming for "show me the output as it generates."
### Can I subscribe to multiple runs at once?
Yes. Use `useRealtimeRunsWithTag` to subscribe to all runs with a specific tag (e.g., `user:123`), or `useRealtimeBatch` for all runs in a batch. Each yields an array of run objects that update in real time.
### Do I need to set up polling or WebSockets?
No. The hooks handle the connection automatically using Trigger.dev's Realtime infrastructure (built on [Electric SQL](/realtime/how-it-works)). Just pass a run ID and an access token.
# 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.define