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
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 options
You can pass the following options to the all SWR hooks:
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
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
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}
;
}
```
See our [Realtime documentation](/realtime) for more information about the type of the run object and more.
### useRealtimeRunsWithTag
The `useRealtimeRunsWithTag` hook allows you to subscribe to multiple runs with a specific tag.
```tsx
"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
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
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
"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.
### useRealtimeRunWithStreams
The `useRealtimeRunWithStreams` hook allows you to subscribe to a run by its ID and also receive any streams that are emitted by the task. See our [Realtime documentation](/realtime#streams) for more information about emitting streams from a task.
```tsx
"use client"; // This is needed for Next.js App Router or other RSC frameworks
import { useRealtimeRunWithStreams } from "@trigger.dev/react-hooks";
export function MyComponent({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
const { run, streams, error } = useRealtimeRunWithStreams(runId, {
accessToken: publicAccessToken,
});
if (error) return Run: {run.id}
))}
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}
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
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
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).
### experimental\_throttleInMs
The `*withStreams` variants of the Realtime hooks accept an `experimental_throttleInMs` option to throttle the updates from the server. This can be useful if you are getting too many updates and want to reduce the number of updates.
```tsx
import { useRealtimeRunsWithStreams } from "@trigger.dev/react-hooks";
export function MyComponent({
runId,
publicAccessToken,
}: {
runId: string;
publicAccessToken: string;
}) {
const { runs, error } = useRealtimeRunsWithStreams(tag, {
accessToken: publicAccessToken,
experimental_throttleInMs: 1000, // Throttle updates to once per second
});
if (error) return Error: {error.message}
;
return (
{runs.map((run) => (
);
}
```
## Examples
Run: {run.id}
))}
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
submit({ foo: "bar" }, { tags: ["tag1", "tag2"] });
```
#### Using the handle object
You can use the `handle` object to initiate a subsequent [realtime hook](/frontend/react-hooks/realtime#userealtimerun) to subscribe to the run.
```tsx
"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
"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
"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}
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 { "userId": "123", "email": "{payload.title}
In this guide, you'll learn how to use Sequin to trigger Trigger.dev tasks from database changes.
## Prerequisites
You are about to create a [regular Trigger.dev task](/tasks-regular) that you will execute when ever a post is inserted or updated in your database. Sequin will detect all the changes on the `posts` table and then send the payload of the post to an API endpoint that will call `tasks.trigger()` to create the embedding and update the database.
As long as you create an HTTP endpoint that Sequin can deliver webhooks to, you can use any web framework or edge function (e.g. Supabase Edge Functions, Vercel Functions, Cloudflare Workers, etc.) to invoke your Trigger.dev task. In this guide, we'll show you how to setup Trigger.dev tasks using Next.js API Routes.
You'll need the following to follow this guide:
* A Next.js project with [Trigger.dev](https://trigger.dev) installed
5. On the next screen, select **Push** to have Sequin send the events to your webhook URL. Click **Continue**.
6. Now, give your consumer a name (i.e. `posts_push_consumer`) and in the **HTTP Endpoint** section select the `local_endpoint` you created above. Add the exact API route you created in the previous step (i.e. `/api/create-embedding-for-post`):
7. Click the **Create Consumer** button.
The self-hosting guide covers two alternative setups. The first option uses a simple setup where you run everything on one server. With the second option, the webapp and worker components are split on two separate machines.
You're going to need at least one Debian (or derivative) machine with Docker and Docker Compose installed. We'll also use Ngrok to expose the webapp to the internet.
## Support
It's dangerous to go alone! Join the self-hosting channel on our [Discord server](https://discord.gg/NQTxt5NA7s).
## Caveats
Loading...
;
}
return (
Run ID: {run.id}
Streams:
-
{Object.entries(streams).map(([key, value]) => (
- {key}: {JSON.stringify(value)} ))}
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"}
Hello ${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 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. # 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. | ## Our library of examples, guides and projects