{error.message}
}
```
## Hook and turn errors
If any lifecycle hook (`onValidateMessages`, `onChatStart`, `onTurnStart`, `hydrateMessages`, `onAction`, `prepareMessages`, `onBeforeTurnComplete`, `onTurnComplete`) or `run()` throws an unhandled exception, the turn loop catches it:
1. Writes `{ type: "error", errorText: error.message }` to the stream
2. Writes a turn-complete chunk to close the turn
3. Waits for the next user message
The conversation stays alive. The user can send another message and continue.
```ts theme={"theme":"css-variables"}
export const myChat = chat.agent({
id: "my-chat",
onTurnStart: async ({ chatId, uiMessages }) => {
// If this throws, the turn ends with an error chunk
// and the agent waits for the next message
await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
},
run: async ({ messages, signal }) => {
return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
},
});
```
### Catching errors in your own hooks
For granular control, wrap your hook code in try/catch and decide what to do. Common patterns:
```ts theme={"theme":"css-variables"}
onValidateMessages: async ({ messages }) => {
try {
return await validateUIMessages({ messages, tools: chatTools });
} catch (err) {
// Log to your error tracking service
Sentry.captureException(err);
// Throw a user-facing error message — this becomes the error chunk
throw new Error("Your message contains invalid data and could not be sent.");
}
},
```
{messages.map(m => /* ... */)}
{error && (
)}
);
}
```
### Distinguishing error types
The `errorText` is just a string, so distinguish error types via prefixes or codes:
```ts theme={"theme":"css-variables"}
// Backend
uiMessageStreamOptions: {
onError: (error) => {
if (error.message.includes("rate limit")) return "RATE_LIMIT: Please wait and try again.";
if (error.message.includes("context_length")) return "CONTEXT_TOO_LONG: Start a new chat.";
return "UNKNOWN: Something went wrong.";
},
},
```
```tsx theme={"theme":"css-variables"}
// Frontend
{error?.message.startsWith("RATE_LIMIT") && {error.message}
(your warm server) participant T as chat.agent run
(Trigger.dev) B->>H: POST first message
(headStart URL) par Step 1 + agent boot in parallel H->>H: streamText step 1
(your model, schema-only tools) H-->>B: SSE: step 1 chunks and H->>T: createSession + trigger run T->>T: boot → wait on session.in end alt finishReason: tool-calls H->>T: handover signal
(partial assistant message) T->>T: execute tools, run step 2 LLM T-->>H: chunks via session.out H-->>B: SSE: step 2 chunks T-->>H: trigger:turn-complete else finishReason: stop (pure text) H->>T: handover-skip signal T->>T: exit (no LLM call) end H-->>B: SSE close Note over B,T: Subsequent turns bypass the handler:
browser writes directly to session.in ```
{messages.map((msg) =>
msg.parts.map((part, i) => {
if (part.state === "approval-requested") {
return (
);
}
// ... render other parts
})
)}
);
}
```
### How it works
1. Model calls a tool with `needsApproval: true` — the turn completes with the tool in `approval-requested` state
2. Frontend shows Approve/Deny buttons
3. User clicks Approve — `addToolApprovalResponse` updates the tool part to `approval-responded`
4. `sendAutomaticallyWhen` returns `true` — `useChat` re-sends the updated assistant message
5. The transport sends the message via input streams — the backend matches it by ID and replaces the existing assistant message in the accumulator
6. `streamText` sees the approved tool, executes it, and streams the result
Tool "{part.type}" wants to run with input:
{JSON.stringify(part.input, null, 2)}
{isReadOnly && (
);
}
```
### How it works
1. When a tab sends a message, the transport "claims" the chatId via `BroadcastChannel`
2. Other tabs detect the claim and enter read-only mode (`isReadOnly: true`)
3. The active tab broadcasts its messages so read-only tabs see updates in real-time
4. When the turn completes, the claim is released. Any tab can send next.
5. Heartbeats detect crashed tabs (10s timeout clears stale claims)
### What `useMultiTabChat` does
* Returns `{ isReadOnly }` for disabling the input UI
* Broadcasts `messages` from the active tab to other tabs
* Calls `setMessages` on read-only tabs when messages arrive from the active tab
* Tracks read-only state via the transport's `BroadcastChannel` coordinator
This chat is active in another tab. Messages are read-only.
)}
{/* message list */}
{editing ? (
) : (
)}
);
}
```
### Branch navigation
To show the `< 2/3 >` sibling switcher, query the tree for siblings at each fork point. This is a frontend concern — the backend exposes the data, the UI navigates it.
```tsx theme={"theme":"css-variables"}
function BranchSwitcher({ message, chatId, siblings }: {
message: UIMessage;
chatId: string;
siblings: { id: string; createdAt: string }[];
}) {
const transport = useTransport();
if (siblings.length <= 1) return null;
const currentIndex = siblings.findIndex((s) => s.id === message.id);
return (
{currentIndex + 1}/{siblings.length}
);
}
```
{messages.map((m) => (
);
}
```
{m.role}:
{m.parts.map((part, i) =>
part.type === "text" ? {part.text} : null
)}
))}
{status === "done" ? `Found ${resultCount} results` : `Researching "${query}"...`}
);
}
// ...other part types
})}
```
The `target` option accepts:
* `"self"` — current run (default)
* `"parent"` — parent task's run
* `"root"` — root task's run (the chat agent)
* A specific run ID string
## Inside `ai.toolExecute`: accessing tool + chat context
When a subtask runs via `execute: ai.toolExecute(task)`, it can read the parent's tool call ID and chat context from inside the subtask body:
```ts theme={"theme":"css-variables"}
import { ai, chat } from "@trigger.dev/sdk/ai";
import type { myChat } from "./chat";
export const mySubtask = schemaTask({
id: "my-subtask",
schema: z.object({ query: z.string() }),
run: async ({ query }) => {
// The AI SDK tool call ID — useful as a stable `data-*` chunk id
const toolCallId = ai.toolCallId();
// Typed chat context — `clientData` is typed off your chat's `clientDataSchema`
const { chatId, clientData } = ai.chatContextOrThrowinject body.triggerConfig.basePayload.metadata.__cf = { botScore, ja4, asn } Edge->>Trigger: POST /api/v1/sessions (rewritten body) Trigger-->>Agent: run boots with payload.metadata.__cf Browser->>Edge: POST /realtime/v1/sessions/{id}/in/append { kind: "message", payload: {...} } Edge->>Edge: strip payload.metadata.__cf
inject payload.metadata.__cf Edge->>Trigger: POST /in/append (rewritten body) Trigger-->>Agent: chat.messages.wait() resolves with payload.metadata.__cf ``` ## Wire payload — the two endpoints to rewrite The signal needs to land in **two** places. Both bodies are JSON; the edge proxy parses, mutates the namespaced key, and re-serializes. ### `POST /api/v1/sessions` — session create The browser's session-create call carries the first-turn metadata under `triggerConfig.basePayload.metadata`. The proxy mutates that: ```ts theme={"theme":"css-variables"} // Before { "type": "chat.agent", "externalId": "conv-123", "taskIdentifier": "my-agent", "triggerConfig": { "basePayload": { "chatId": "conv-123", "trigger": "preload", "metadata": { "userId": "user-456" } } } } // After { "type": "chat.agent", "externalId": "conv-123", "taskIdentifier": "my-agent", "triggerConfig": { "basePayload": { "chatId": "conv-123", "trigger": "preload", "metadata": { "userId": "user-456", "__cf": { "botScore": 95, "ja4": "...", "asn": 13335, "country": "US" } } } } } ``` ### `POST /realtime/v1/sessions/{id}/in/append` — every follow-up turn The body is a JSON-serialized `ChatInputChunk`. The proxy parses it, checks `kind === "message"`, and mutates `payload.metadata`: ```ts theme={"theme":"css-variables"} // Before { "kind": "message", "payload": { "message": { "id": "u-2", "role": "user", "parts": [{ "type": "text", "text": "..." }] }, "chatId": "conv-123", "trigger": "submit-message", "metadata": { "userId": "user-456" } } } // After { "kind": "message", "payload": { "message": { ... }, "chatId": "conv-123", "trigger": "submit-message", "metadata": { "userId": "user-456", "__cf": { "botScore": 95, "ja4": "...", "asn": 13335, "country": "US" } } } } ``` Both bodies stay well under the [per-record cap on `/in/append`](/docs/ai-chat/client-protocol#step-3-send-messages-stops-and-actions) — a typical trust object is \~200 bytes. Other paths — `.out` SSE, `/api/v1/auth/jwt/claims`, anything else — pass through the proxy untouched. The SSE stream in particular must not be buffered; preserve the response body as-is. ## Cloudflare Worker reference implementation A complete worker that proxies all paths to `TRIGGER_API_UPSTREAM` and injects `__cf` on the two body-write endpoints: ```ts theme={"theme":"css-variables"} export interface Env { TRIGGER_API_UPSTREAM: string; // e.g. "https://api.trigger.dev" } type CfTrustData = { botScore: number; ja4: string; asn: number; country: string; }; function readCfTrustData(request: Request): CfTrustData { const cf = (request as Request & { cf?: Record
{/* Render messages */}
{messages.map((msg) => (
);
}
```
### Hook API
| Property/Method | Type | Description |
| ----------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| `pending` | `PendingMessage[]` | Current pending messages with `id`, `text`, `mode`, and `injected` status |
| `steer(text)` | `(text: string) => void` | Send a steering message during streaming, or normal message when ready |
| `queue(text)` | `(text: string) => void` | Queue for next turn during streaming, or send normally when ready |
| `promoteToSteering(id)` | `(id: string) => void` | Convert a queued message to steering (sends via input stream immediately) |
| `isInjectionPoint(part)` | `(part: unknown) => boolean` | Check if an assistant message part is an injection confirmation |
| `getInjectedMessageIds(part)` | `(part: unknown) => string[]` | Get message IDs from an injection point |
| `getInjectedMessages(part)` | `(part: unknown) => InjectedMessage[]` | Get messages (id + text) from an injection point |
### PendingMessage
| Field | Type | Description |
| ---------- | ------------------------ | --------------------------------------- |
| `id` | `string` | Unique message ID |
| `text` | `string` | Message text |
| `mode` | `"steering" \| "queued"` | How the message is being handled |
| `injected` | `boolean` | Whether the backend confirmed injection |
### Message lifecycle
* **Steering messages** are sent via `transport.sendPendingMessage()` immediately. They appear as purple pending bubbles. If injected, they disappear from the overlay and render inline at the injection point. If not injected, the backend answers them as the next turn once the response finishes; the client does not need to re-send them.
* **Queued messages** stay client-side until the turn completes, then auto-send as the next turn via `sendMessage()`. They can be promoted to steering mid-stream by clicking "Steer instead".
* **Promoted messages** are queued messages that were converted to steering. They get sent via input stream immediately and follow the steering lifecycle from that point.
## Transport: sendPendingMessage
The `TriggerChatTransport` exposes a `sendPendingMessage` method for sending messages via input stream without disrupting the active stream subscription:
```ts theme={"theme":"css-variables"}
const sent = await transport.sendPendingMessage(chatId, {
id: crypto.randomUUID(),
role: "user",
parts: [{ type: "text", text: "and compare to vercel" }],
}, { model: "gpt-4o" });
```
Unlike `sendMessage()` from useChat, this does NOT:
* Add the message to useChat's local state
* Cancel the active stream subscription
* Start a new response stream
The `usePendingMessages` hook calls this internally — you typically don't need to use it directly.
## Coexistence with compaction
Pending message injection and compaction both use `prepareStep`. When both are configured, the auto-injected `prepareStep` handles them in order:
1. **Compaction** runs first — checks threshold, generates summary if needed
2. **Injection** runs second — pending messages are appended to either the compacted or original messages
This means injected messages are always included after compaction, ensuring the LLM sees both the compressed history and the new steering input.
# Prompt caching
Source: https://trigger.dev/docs/ai-chat/prompt-caching
Cache the stable prefix of your agent's prompt with Anthropic prompt caching to cut token cost and latency on every turn.
**Prompt caching lets a provider reuse the unchanged prefix of your prompt across requests, billing it at a fraction of the input price and skipping re-processing.** With Anthropic, cache reads cost \~10% of base input tokens, so a long, stable system prompt or a growing conversation history pays full price once and reads cheaply on every turn after.
Caching is a **byte-exact prefix match**: any change in the prefix invalidates everything after it. A multi-turn agent is the ideal case — the system prompt, tools, and earlier turns are identical turn over turn, so the cacheable prefix only grows. `chat.agent` is built to keep that prefix stable across turns, suspends, and resumes; this page shows how to place the cache breakpoints and verify they're hitting.
Caching is provider-specific. This guide covers Anthropic (`@ai-sdk/anthropic`), where you opt in per breakpoint with `providerOptions.anthropic.cacheControl`. Other providers cache differently, and most cache automatically — see [Other providers](#other-providers).
## What you cache, and where
A request renders as `tools` → `system` → `messages`. There are three prefix regions worth caching, in order:
| Region | How to cache it | Stability |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| System prompt (+ tools) | `cacheControl` / `systemProviderOptions` on `chat.toStreamTextOptions()`, or `providerOptions` on `chat.prompt.set()` | Set once, never changes — the highest-value target |
| Conversation history | `prepareMessages` adds a breakpoint to the last message | Grows append-only across turns |
| Tool definitions | Stable as long as your tool set doesn't change between turns | Render at position 0 — changing them invalidates everything |
`chat.agent` preserves `providerOptions` through message persistence and rehydration, so a breakpoint you place survives a suspend/resume or a page refresh. The recommended way to place message breakpoints is `prepareMessages` (below) rather than baking `cacheControl` into stored messages — `prepareMessages` runs on every prompt-assembly path, including after compaction, so the breakpoint is always in the right place.
## Cache the system prompt
The system prompt (your `chat.prompt` text plus any skills preamble) is usually the largest stable block, so it's the first thing to cache. `chat.toStreamTextOptions()` returns `system` as a plain string by default; opt into caching and it returns a structured system message carrying the cache breakpoint instead.
{msg.role === "assistant" ? (
msg.parts.map((part, i) =>
pending.isInjectionPoint(part) ? (
// Render injected messages inline at the injection point
))}
{/* Render pending messages */}
{pending.pending.map((msg) => (
{pending.getInjectedMessages(part).map((m) => (
) : (
{m.text}
))}
{msg.text}
{msg.mode === "steering" ? "Steering" : "Queued"}
{msg.mode === "queued" && status === "streaming" && (
)}
))}
{/* Send form */}
{messages.map((m) => (
);
}
```
{m.role}:
{m.parts.map((part, i) =>
part.type === "text" ? {part.text} : null
)}
))}
(runs come and go)"] R -- "text, reasoning, tool calls,
data parts" --> OUT([Session .out]) OUT --> C ``` `chat.agent` is built on Sessions. You can also use them directly for any pattern that needs durable bi-directional streaming across runs: long-lived agent inboxes, multi-step approval flows, server-to-server pipelines that survive worker restarts. ## A minimal example A task that echoes whatever lands on its input stream, and a backend that starts the session, sends a message, and reads the reply: ```ts trigger/inbox.ts theme={"theme":"css-variables"} import { task, sessions } from "@trigger.dev/sdk"; export const inboxAgent = task({ id: "inbox-agent", run: async (payload: { sessionId: string }) => { const session = sessions.open(payload.sessionId); while (true) { // Suspends the run (no compute billed) until a record arrives. const next = await session.in.wait<{ text: string }>({ timeout: "1h" }); if (!next.ok) return; await session.out.append({ type: "reply", text: `echo: ${next.output.text}` }); } }, }); ``` ```ts Your backend theme={"theme":"css-variables"} import { sessions } from "@trigger.dev/sdk"; // Atomically create the session AND trigger its first run. await sessions.start({ type: "inbox", externalId: userId, taskIdentifier: "inbox-agent", triggerConfig: { basePayload: { sessionId: userId } }, }); const session = sessions.open(userId); await session.in.send({ text: "hello" }); const stream = await session.out.read({ signal: AbortSignal.timeout(30_000) }); for await (const chunk of stream) { console.log(chunk); // { type: "reply", text: "echo: hello" } } ``` The run can suspend, crash, or be replaced between the `send` and the `read` — the streams are durable, so nothing is lost and the client code doesn't change. ## Sessions and runs One Session spans many runs over its lifetime. The Session row tracks `currentRunId`; the runs do the work: * **First run**: created atomically by `sessions.start` (no gap where the session exists but nothing is listening). * **Idle suspend**: a run blocked on `in.wait` suspends and frees compute. A new record on `.in` wakes it. * **Continuation**: when a run ends (idle timeout, `chat.endRun`, a crash, a version upgrade), the next incoming record triggers a fresh run against the same Session. The new run picks up the streams where the old one left off. This is what makes a Session the durable identity for a conversation: runs are an execution detail, the Session (and its `externalId`) is what your clients address. See [How it works](/docs/ai-chat/how-it-works) for how `chat.agent` drives this loop. ## When to reach for Sessions directly `chat.agent` handles 90% of chat-shaped workloads — message accumulation, the turn loop, stop signals, lifecycle hooks. Use the raw `sessions` API when you need any of: * **Non-chat conversational state**: an agent inbox where each "turn" is a webhook event rather than a UI message. * **Server-to-server bi-directional streaming** where an external service produces records the task consumes (and vice-versa) over the same durable channel. * **A custom turn loop** where the agent abstraction doesn't fit but you still want session-survival across runs. For chat use cases, prefer [`chat.agent`](/docs/ai-chat/backend#chat-agent) or [`chat.createSession`](/docs/ai-chat/backend#chat-createsession). ## `sessions` namespace ```ts theme={"theme":"css-variables"} import { sessions } from "@trigger.dev/sdk"; ``` ### `sessions.start(body, requestOptions?)` Atomically create a Session row and trigger its first run. Idempotent on `(env, externalId)` — two concurrent calls with the same `externalId` converge to one session. ```ts theme={"theme":"css-variables"} const { id, runId, publicAccessToken, isCached } = await sessions.start({ type: "chat.agent", externalId: chatId, taskIdentifier: "my-chat", triggerConfig: { tags: [`chat:${chatId}`], basePayload: { /* whatever your task's payload shape is */ }, }, }); ``` | Field | Type | Notes | | ---------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `string` | Free-form discriminator. `chat.agent` uses `"chat.agent"`. | | `externalId` | `string?` | Your stable identity. Cannot start with `session_` (reserved). | | `taskIdentifier` | `string` | Task this session triggers runs against. | | `triggerConfig` | `SessionTriggerConfig` | Trigger options applied to every run: `tags` (up to 10, same as [run tags](/docs/tags); the chat helpers such as `chat.createStartSessionAction` and `AgentChat` add a `chat:{chatId}` tag themselves, which uses one slot. Direct `sessions.start` callers get all 10 and must add any chat tag themselves), `queue`, `machine`, `maxAttempts`, `idleTimeoutInSeconds`, `basePayload`. | | `tags` | `string[]?` | Up to 10 tags on the Session row (separate from `triggerConfig.tags`). | | `metadata` | `Record
Waiting…
; } ``` `useSessionStreamChannel` has the same options and return shape as [`useSessionStream`](/docs/realtime/react-hooks/session-stream) (`io`, `from`, `maxRecords`, `lastEventId`, `onRecords`, `onControl`, `throttleInMs`, `timeoutInSeconds`), plus the typed channel generic. A bare name string works without the generic, with `records` typed `unknown`. The client writes the `.in` control with a session handle: `sessions.open(sessionId).channel(screenshots).in.send({ paused: true })`. This appends to the channel and does not wake a run. ## From MCP An MCP client can read and write a session's channels with two [MCP tools](/docs/mcp-tools): `read_session_channel` drains a channel's records (with an optional `timeoutInSeconds` to wait for the next one), and `write_session_channel` appends a record to a channel's `.in` to send control input to a running agent. Reading `.out` gives the producer feed (e.g. the screencast); writing `.in` does not wake a run, and `.out` stays producer-only. ## Retention A side channel's streams are bounded by the same retention as the rest of your realtime streams: streams are created on demand when first written and age out on your plan's retention window, with empty streams cleaned up automatically. A channel needs no separate setup or trimming.{/* m.parts narrowed for your UIMessage subtype */}
));
}
```
You can also import `InferChatUIMessage` from `@trigger.dev/sdk/ai` in non-React modules.
## Typed client data with `chat.withClientData`
`chat.withClientData({ schema })` returns a [ChatBuilder](#chatbuilder) that fixes the client data schema. Managed-agent hooks and `run` receive typed `clientData` without needing `clientDataSchema` in `.agent()` options. A `.customAgent()` run receives the parsed schema output in `payload.metadata`, and `chat.createSession()` yields it as `turn.clientData`.
```ts theme={"theme":"css-variables"}
import { chat } from "@trigger.dev/sdk/ai";
import { z } from "zod";
export const myChat = chat
.withClientData({
schema: z.object({ userId: z.string(), model: z.string().optional() }),
})
.agent({
id: "my-chat",
onPreload: async ({ clientData }) => {
// clientData is typed as { userId: string; model?: string }
await initUser(clientData.userId);
},
run: async ({ messages, clientData, signal }) => {
return streamText({
model: getModel(clientData.model),
messages,
abortSignal: signal,
stopWhen: stepCountIs(15),
});
},
});
```
The schema runs at runtime for both `.agent()` and `.customAgent()`. Custom agents validate the initial payload and later `chat.messages` frames. Invalid frames are not passed to user code. Async reads emit an error chunk followed by `turn-complete`; `chat.messages.on()` reports through `onClientDataValidationError` and the task log so it does not end an active response. Without a schema, metadata is passed through unchanged.
`withClientData` also takes `reportErrorAt` and `onValidationError` alongside `schema`. See [chat.withClientData](/docs/ai-chat/reference#chatwithclientdata) for both, and [Validating client data](/docs/ai-chat/custom-agents#validating-client-data) for the custom-agent walkthrough.
## ChatBuilder
Both `chat.withUIMessage()` and `chat.withClientData()` return a **ChatBuilder** — a chainable object that accumulates configuration before creating the agent with `.agent()`.
Builder methods can be chained in any order:
```ts theme={"theme":"css-variables"}
export const myChat = chat
.withUIMessage6.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](/docs/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: