chore: import upstream snapshot with attribution

2026-07-13 13:32:57 +08:00
commit cd420f9332
4811 changed files with 884702 additions and 0 deletions
@@ -0,0 +1,194 @@
+---
+title: "Trigger tasks from React"
+sidebarTitle: Triggering
+description: "Trigger background tasks from React components and optionally subscribe to their progress or stream their output."
+---
+
+Trigger tasks directly from your React components. You can fire-and-forget, or trigger and immediately subscribe to the run's progress or streamed output.
+
+<Note>
+  For triggering tasks from your frontend, you need to use “trigger” tokens. These can only be used
+  once to trigger a task and are more secure than regular Public Access Tokens. To learn more about
+  how to create and use these tokens, see our [Trigger
+  Tokens](/realtime/auth#trigger-tokens-for-frontend-triggering-only) documentation.
+</Note>
+
+## Hooks
+
+We provide three hooks for triggering tasks from your frontend application:
+
+- `useTaskTrigger` - Trigger a task from your frontend application.
+- `useRealtimeTaskTrigger` - Trigger a task from your frontend application and subscribe to the run.
+- `useRealtimeTaskTriggerWithStreams` - Trigger a task from your frontend application and subscribe to the run, and also receive any streams that are emitted by the task.
+
+### useTaskTrigger
+
+The `useTaskTrigger` hook allows you to trigger a task from your frontend application.
+
+```tsx
+"use client"; // This is needed for Next.js App Router or other RSC frameworks
+
+import { useTaskTrigger } from "@trigger.dev/react-hooks";
+import type { myTask } from "@/trigger/myTask";
+//     👆 This is the type of your task, include this to get type-safety
+
+export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
+  //                         pass the type of your task here 👇
+  const { submit, handle, error, isLoading } = useTaskTrigger<typeof myTask>("my-task", {
+    accessToken: publicAccessToken, // 👈 this is the "trigger" token
+  });
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (handle) {
+    return <div>Run ID: {handle.id}</div>;
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```
+
+`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](/realtime/react-hooks/subscribe#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 } = useTaskTrigger<typeof myTask>("my-task", {
+    accessToken: publicAccessToken, // 👈 this is the "trigger" token
+  });
+
+  //     use the handle object to preserve type-safety 👇
+  const { run, error: realtimeError } = useRealtimeRun(handle, {
+    accessToken: handle?.publicAccessToken,
+    enabled: !!handle, // Only subscribe to the run if the handle is available
+  });
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (handle) {
+    return <div>Run ID: {handle.id}</div>;
+  }
+
+  if (realtimeError) {
+    return <div>Error: {realtimeError.message}</div>;
+  }
+
+  if (run) {
+    return <div>Run ID: {run.id}</div>;
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```
+
+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 } = useRealtimeTaskTrigger<typeof myTask>("my-task", {
+    accessToken: publicAccessToken,
+  });
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  // This is the Realtime run object, which will automatically update when the run changes
+  if (run) {
+    return <div>Run ID: {run.id}</div>;
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```
+
+### 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 <div>Error: {error.message}</div>;
+  }
+
+  if (streams && run) {
+    const text = streams.openai?.map((part) => part).join("");
+
+    return (
+      <div>
+        <div>Run ID: {run.id}</div>
+        <div>{text}</div>
+      </div>
+    );
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```