@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/realtime/react-hooks/streams.mdx

@@ -0,0 +1,517 @@
+---
+title: "Stream data to React (AI, files, progress)"
+sidebarTitle: "Streaming"
+description: "Display AI/LLM output token by token, stream file chunks, or pipe any continuous data from a background task into your React components."
+---
+
+**Display AI responses as they generate, stream file processing results, or pipe any continuous data from a running task into your React components.** Unlike [progress and status hooks](/realtime/react-hooks/subscribe) (which track run state), streaming hooks give you the raw data your task produces while it runs.
+
+<Note>
+  To learn how to emit streams from your tasks, see [Streaming data from tasks](/tasks/streams).
+</Note>
+
+## useRealtimeStream (Recommended)
+
+<Note>
+  Available in SDK version **4.1.0 or later**. This is the recommended way to consume streams in
+  your React components.
+</Note>
+
+The `useRealtimeStream` hook allows you to subscribe to a specific stream by its run ID and stream key. This hook is designed to work seamlessly with [defined streams](/tasks/streams#defining-typed-streams-recommended) for full type safety.
+
+### Basic Usage
+
+```tsx
+"use client";
+
+import { useRealtimeStream } from "@trigger.dev/react-hooks";
+
+export function StreamViewer({
+  runId,
+  publicAccessToken,
+}: {
+  runId: string;
+  publicAccessToken: string;
+}) {
+  const { parts, error } = useRealtimeStream<string>(runId, "ai-output", {
+    accessToken: publicAccessToken,
+  });
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (!parts) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {parts.map((part, i) => (
+        <span key={i}>{part}</span>
+      ))}
+    </div>
+  );
+}
+```
+
+### With Defined Streams
+
+The recommended approach is to use defined streams for full type safety:
+
+```tsx
+"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 <div>Error: {error.message}</div>;
+  if (!parts) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {parts.map((part, i) => (
+        <span key={i}>{part}</span>
+      ))}
+    </div>
+  );
+}
+```
+
+### Streaming AI Responses
+
+Here's a complete example showing how to display streaming AI responses:
+
+```tsx
+"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 <div>Error: {error.message}</div>;
+  if (!parts) return <div>Loading stream...</div>;
+
+  const text = parts.join("");
+
+  return (
+    <div className="prose">
+      <Streamdown isAnimating={true}>{text}</Streamdown>
+    </div>
+  );
+}
+```
+
+### Options
+
+The `useRealtimeStream` hook accepts the following options:
+
+```tsx
+const { parts, lastEventId, error } = useRealtimeStream(streamOrRunId, streamKeyOrOptions, {
+  accessToken: "pk_...", // Required: Public access token
+  baseURL: "https://api.trigger.dev", // Optional: Custom API URL
+  timeoutInSeconds: 60, // Optional: Timeout (default: 60)
+  from: "beginning", // Optional: "beginning" (default) or "latest"
+  maxParts: 100, // Optional: keep only the most recent N parts (default: unbounded)
+  lastEventId: undefined, // Optional: resume cursor (takes precedence over startIndex)
+  startIndex: 0, // Optional: start from a specific chunk index
+  throttleInMs: 16, // Optional: Throttle updates (default: 16ms)
+  onData: (chunk) => {}, // Optional: callback for each chunk
+  onParts: (batch) => {}, // Optional: callback per throttled batch, each with its event id
+  refreshAccessToken: async () => "pk_...", // Optional: mint a fresh token on expiry
+});
+```
+
+The hook returns `lastEventId`, the cursor of the last part it received. Persist it and pass it back as the `lastEventId` option to resume later.
+
+### Live view: start from the latest record
+
+By default a subscriber replays the whole stream history, then live-tails. Pass `from: "latest"` to start at the current tail (the latest record, then live updates) instead of replaying, and `maxParts` to keep memory bounded. Together they give a last-value view:
+
+```tsx
+"use client";
+
+import { useRealtimeStream } from "@trigger.dev/react-hooks";
+
+export function LatestFrame({ runId, accessToken }: { runId: string; accessToken: string }) {
+  const { parts } = useRealtimeStream<{ url: string }>(runId, "frames", {
+    accessToken,
+    from: "latest", // start at the latest frame, then live updates
+    maxParts: 1, // keep just the most recent frame
+  });
+
+  const frame = parts.at(-1);
+  return frame ? <img src={frame.url} alt="latest frame" /> : null;
+}
+```
+
+<Note>
+  `from: "latest"` requires a server that supports it. Against an older server a client that passes
+  it degrades safely to a full replay.
+</Note>
+
+### Resume across a page reload
+
+The hook resumes automatically across a component remount. A full page reload clears in-memory
+state, so to resume there, persist the returned `lastEventId` and pass it back on the next load. The
+subscription then continues after that record with no replay and no gap:
+
+```tsx
+const cursorKey = `frames-cursor:${runId}`; // scope the key to this stream
+const saved = localStorage.getItem(cursorKey) ?? undefined;
+
+const { parts, lastEventId } = useRealtimeStream<{ url: string }>(runId, "frames", {
+  accessToken,
+  lastEventId: saved, // resume where the previous session left off
+  onParts: (batch) => localStorage.setItem(cursorKey, batch.at(-1)!.id),
+});
+```
+
+### Refresh an expired access token
+
+Public access tokens are short-lived. For a long-running subscription, pass `refreshAccessToken` to
+mint a fresh token when the server rejects the connection with a 401/403. The subscription re-mints
+once and reconnects; with no refresher, auth errors stay terminal:
+
+```tsx
+const { parts } = useRealtimeStream<{ url: string }>(runId, "frames", {
+  accessToken,
+  refreshAccessToken: async () => {
+    const res = await fetch("/api/realtime-token"); // your backend mints a fresh public token
+    return (await res.json()).token;
+  },
+});
+```
+
+`refreshAccessToken` is also available on [`useApiClient` and `TriggerAuthContext`](/realtime/auth), so every hook under a provider shares one refresher.
+
+### Using Default Stream
+
+You can omit the stream key to use the default stream:
+
+```tsx
+const { parts, error } = useRealtimeStream<string>(runId, {
+  accessToken: publicAccessToken,
+});
+```
+
+For more information on defining and using streams, see the [Streaming data from tasks](/tasks/streams) documentation.
+
+## useInputStreamSend
+
+The `useInputStreamSend` hook lets you send data from your frontend into a running task's [input stream](/tasks/streams#input-streams). Use it for cancel buttons, approval forms, or any UI that needs to push typed data into a running task.
+
+### Basic usage
+
+Pass the input stream's `id` (string), the run ID, and options such as `accessToken`. You typically get `runId` and `accessToken` from the object returned when you trigger the task (e.g. `handle.id`, `handle.publicAccessToken`). The hook returns `send`, `isLoading`, `error`, and `isReady`:
+
+```tsx
+"use client";
+
+import { useInputStreamSend } from "@trigger.dev/react-hooks";
+import { approval } from "@/trigger/streams";
+
+export function ApprovalForm({
+  runId,
+  accessToken,
+}: {
+  runId: string;
+  accessToken: string;
+}) {
+  const { send, isLoading, isReady } = useInputStreamSend(
+    approval.id,
+    runId,
+    { accessToken }
+  );
+
+  return (
+    <button
+      disabled={!isReady || isLoading}
+      onClick={() => send({ approved: true, reviewer: "alice" })}
+    >
+      Approve
+    </button>
+  );
+}
+```
+
+With a generic for type-safe payloads when not using a defined stream:
+
+```tsx
+type ApprovalPayload = { approved: boolean; reviewer: string };
+const { send } = useInputStreamSend<ApprovalPayload>("approval", runId, {
+  accessToken,
+});
+send({ approved: true, reviewer: "alice" });
+```
+
+### Options and return value
+
+- **`streamId`**: The input stream identifier (string). Use the `id` from your defined stream (e.g. `approval.id`) or the same string you used in `streams.input<T>({ id: "approval" })`.
+- **`runId`**: The run to send input to. When `runId` is undefined, `isReady` is false and `send` will not trigger.
+- **`options`**: `accessToken` (required for client usage), `baseURL` (optional). See [Realtime auth](/realtime/auth) for generating a public access token with the right scopes (e.g. input streams write for that run).
+
+Return value:
+
+- **`send(data)`**: Sends typed data to the input stream. Uses SWR mutation under the hood.
+- **`isLoading`**: True while a send is in progress.
+- **`error`**: Set if the last send failed.
+- **`isReady`**: True when both `runId` and access token are available.
+
+For receiving input stream data inside a task (`.wait()`, `.once()`, `.on()`), see [Input Streams](/tasks/streams#input-streams) in the Streams doc.
+
+## useRealtimeRunWithStreams
+
+<Note>
+  For new projects, we recommend using `useRealtimeStream` instead (available in SDK 4.1.0+). This
+  hook is still supported for backward compatibility and use cases where you need to subscribe to
+  both the run and all its streams at once.
+</Note>
+
+The `useRealtimeRunWithStreams` hook allows you to subscribe to a run by its ID and also receive any streams that are emitted by the task. This is useful when you need to access both the run metadata and multiple streams simultaneously.
+
+```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 <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <div>Run: {run.id}</div>
+      <div>
+        {Object.keys(streams).map((stream) => (
+          <div key={stream}>Stream: {stream}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+You can also provide the type of the streams to the `useRealtimeRunWithStreams` hook to get type-safety:
+
+```tsx
+import { useRealtimeRunWithStreams } 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({
+  runId,
+  publicAccessToken,
+}: {
+  runId: string;
+  publicAccessToken: string;
+}) {
+  const { run, streams, error } = useRealtimeRunWithStreams<typeof myTask, STREAMS>(runId, {
+    accessToken: publicAccessToken,
+  });
+
+  if (error) return <div>Error: {error.message}</div>;
+
+  const text = streams.openai?.map((part) => part).join("");
+
+  return (
+    <div>
+      <div>Run: {run.id}</div>
+      <div>{text}</div>
+    </div>
+  );
+}
+```
+
+As you can see above, each stream is an array of the type you provided, keyed by the stream name. If instead of a pure text stream you have a stream of objects, you can provide the type of the object:
+
+```tsx
+import type { TextStreamPart } from "ai";
+import type { myTask } from "@/trigger/myTask";
+
+type STREAMS = { openai: TextStreamPart<{}> };
+
+export function MyComponent({
+  runId,
+  publicAccessToken,
+}: {
+  runId: string;
+  publicAccessToken: string;
+}) {
+  const { run, streams, error } = useRealtimeRunWithStreams<typeof myTask, STREAMS>(runId, {
+    accessToken: publicAccessToken,
+  });
+
+  if (error) return <div>Error: {error.message}</div>;
+
+  const text = streams.openai
+    ?.filter((stream) => stream.type === "text-delta")
+    ?.map((part) => part.text)
+    .join("");
+
+  return (
+    <div>
+      <div>Run: {run.id}</div>
+      <div>{text}</div>
+    </div>
+  );
+}
+```
+
+### Streaming AI responses with useRealtimeRunWithStreams
+
+Here's an example showing how to display streaming OpenAI responses using `useRealtimeRunWithStreams`:
+
+```tsx
+import { useRealtimeRunWithStreams } from "@trigger.dev/react-hooks";
+import type { aiStreaming, STREAMS } from "./trigger/ai-streaming";
+
+function MyComponent({ runId, publicAccessToken }: { runId: string; publicAccessToken: string }) {
+  const { streams } = useRealtimeRunWithStreams<typeof aiStreaming, STREAMS>(runId, {
+    accessToken: publicAccessToken,
+  });
+
+  if (!streams.openai) {
+    return <div>Loading...</div>;
+  }
+
+  const text = streams.openai.join(""); // `streams.openai` is an array of strings
+
+  return (
+    <div>
+      <h2>OpenAI response:</h2>
+      <p>{text}</p>
+    </div>
+  );
+}
+```
+
+### AI SDK with tools
+
+When using the AI SDK with tools with `useRealtimeRunWithStreams`, you can access tool calls and results:
+
+```tsx
+import { useRealtimeRunWithStreams } from "@trigger.dev/react-hooks";
+import type { aiStreamingWithTools, STREAMS } from "./trigger/ai-streaming";
+
+function MyComponent({ runId, publicAccessToken }: { runId: string; publicAccessToken: string }) {
+  const { streams } = useRealtimeRunWithStreams<typeof aiStreamingWithTools, STREAMS>(runId, {
+    accessToken: publicAccessToken,
+  });
+
+  if (!streams.openai) {
+    return <div>Loading...</div>;
+  }
+
+  // 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 (
+    <div>
+      <h2>OpenAI response:</h2>
+      <p>{text}</p>
+      <h2>Weather:</h2>
+      <p>
+        {weatherLocation
+          ? `The weather in ${weatherLocation} is ${weather} degrees.`
+          : "No weather data"}
+      </p>
+    </div>
+  );
+}
+```
+
+### Throttling updates
+
+The `useRealtimeRunWithStreams` hook accepts a `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 { useRealtimeRunWithStreams } from "@trigger.dev/react-hooks";
+
+export function MyComponent({
+  runId,
+  publicAccessToken,
+}: {
+  runId: string;
+  publicAccessToken: string;
+}) {
+  const { run, streams, error } = useRealtimeRunWithStreams(runId, {
+    accessToken: publicAccessToken,
+    throttleInMs: 1000, // Throttle updates to once per second
+  });
+
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <div>Run: {run.id}</div>
+      {/* Display streams */}
+    </div>
+  );
+}
+```
+
+All other options (accessToken, baseURL, enabled, id) work the same as the other realtime hooks.
+
+For the newer `useRealtimeStream` hook, use the `throttleInMs` option instead (see [options above](#options)).
+
+## Frequently asked questions
+
+### How do I stream AI/LLM responses from a background task to React?
+
+Define a typed stream in your task with `streams.define<string>()`, pipe your AI SDK response to it with `.pipe()`, then consume it in your component with `useRealtimeStream`. See [Streaming data from tasks](/tasks/streams) for the task-side setup.
+
+### What's the difference between streaming and run updates?
+
+[Run updates](/realtime/react-hooks/subscribe) track **run state** (status, metadata, tags). Streaming (this page) pipes **continuous data** your task produces. Use run updates for progress bars and status badges. Use streaming for AI chat output, live logs, or file processing results. You can use both at the same time.
+
+### Can I send data back into a running task from React?
+
+Yes. Use the `useInputStreamSend` hook to send data into a running task's input stream. This is useful for cancel buttons, user approvals, or any interactive flow. See [Input Streams](/tasks/streams#input-streams) for the full guide.
+
+### Do streams work with the Vercel AI SDK?
+
+Yes. You can pipe a Vercel AI SDK `streamText` response directly into a Trigger.dev stream using `.pipe()`. The [Streaming data from tasks](/tasks/streams) page has a complete AI streaming example.