Index of every page on this site: llms.txt
All skills
triggerdotdev avatar

/trigger-realtime

@43d4ee1 official
by Trigger.devtriggerdotdev/skills35 stars
7
Run it yourself

Trigger.dev client/frontend surface: subscribe to runs in realtime (runs.subscribeToRun and the @trigger.dev/react-hooks hook useRealtimeRun), consume metadata and AI/text streams in React (useRealtimeStream), trigger tasks from the browser (useTaskTrigger, useRealtimeTaskTrigger), and mint scoped frontend credentials with auth.createPublicToken / auth.createTriggerPublicToken. Load when wiring a frontend (React/Next.js/Remix) or backend-for-frontend to show live run progress, status badges, token streams, trigger buttons, or wait-token approval UIs. NOT for writing the backend task itself (streams.define / metadata.set is trigger-tasks territory); this is the consumer side.

Use this Skill: https://skilld.dev/gh/triggerdotdev/skills/trigger-realtime

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈175 tokens for metadata: the name and description. ≈2.4k when used: this file.

Description uses 8.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈702 characters, or 8.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Realtime and Frontend

The consumer side of Trigger.dev's run state and streams: read live run updates, render AI/text streams, and trigger tasks from a browser. Hooks come from @trigger.dev/react-hooks; token minting and backend subscription come from @trigger.dev/sdk.

Setup

npm add @trigger.dev/react-hooks   # frontend hooks (React/Next.js/Remix)
# @trigger.dev/sdk is already installed for the backend

The flow is always: mint a scoped token in the backend, pass it to the frontend, subscribe with a hook.

// backend (API route / server action)
import { auth } from "@trigger.dev/sdk";

const publicAccessToken = await auth.createPublicToken({
  scopes: { read: { runs: ["run_1234"] } }, // a token with no scopes is useless
});
// frontend
"use client";
import { useRealtimeRun } from "@trigger.dev/react-hooks";

export function RunStatus({ runId, publicAccessToken }: { runId: string; publicAccessToken: string }) {
  const { run, error } = useRealtimeRun(runId, { accessToken: publicAccessToken });
  if (error) return <div>Error: {error.message}</div>;
  if (!run) return <div>Loading...</div>;
  return <div>Run: {run.status}</div>;
}

There are two token kinds: Public Access Tokens (read/subscribe, from auth.createPublicToken) and Trigger Tokens (trigger-from-browser, single-use, from auth.createTriggerPublicToken). Both default to a 15 minute expiry.

Core patterns

1. Subscribe to a run and render metadata progress

metadata is Record<string, DeserializedJson>, so nested values need a cast.

"use client";
import { useRealtimeRun } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";

export function Progress({ runId, publicAccessToken }: { runId: string; publicAccessToken: string }) {
  const { run, error } = useRealtimeRun<typeof myTask>(runId, { accessToken: publicAccessToken });
  if (error) return <div>Error: {error.message}</div>;
  if (!run) return <div>Loading...</div>;
  const progress = run.metadata?.progress as { percentage?: number } | undefined;
  return <div>{run.status}: {progress?.percentage ?? 0}%</div>;
}

Pass onComplete: (run, error) => {} to react when the run finishes.

2. Status-only subscription with skipColumns

For a badge or progress bar you do not need payload/output. Skipping them reduces wire size and avoids "Large HTTP Payload" warnings.

const { run } = useRealtimeRun(runId, {
  accessToken: publicAccessToken,
  skipColumns: ["payload", "output"],
});

You can skip any of: payload, output, metadata, startedAt, delayUntil, queuedAt, expiredAt, completedAt, number, isTest, usageDurationMs, costInCents, baseCostInCents, ttl, payloadType, outputType, runTags, error.

3. Trigger from the browser with a Trigger Token

accessToken here is a Trigger Token (auth.createTriggerPublicToken), not a Public Access Token.

"use client";
import { useTaskTrigger } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";

export function TriggerButton({ triggerToken }: { triggerToken: string }) {
  const { submit, handle, isLoading } = useTaskTrigger<typeof myTask>("my-task", {
    accessToken: triggerToken,
  });
  if (handle) return <div>Run ID: {handle.id}</div>;
  return (
    <button onClick={() => submit({ foo: "bar" }, { tags: ["user:123"] })} disabled={isLoading}>
      {isLoading ? "Triggering..." : "Run"}
    </button>
  );
}

submit(payload, options?) takes the same options as a backend trigger call.

4. Trigger and subscribe in one hook

"use client";
import { useRealtimeTaskTrigger } from "@trigger.dev/react-hooks";
import type { myTask } from "@/trigger/myTask";

export function Runner({ publicAccessToken }: { publicAccessToken: string }) {
  const { submit, run, isLoading } = useRealtimeTaskTrigger<typeof myTask>("my-task", {
    accessToken: publicAccessToken,
  });
  if (run) return <div>{run.status}</div>;
  return <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>Run</button>;
}

Use useRealtimeTaskTriggerWithStreams<typeof myTask, STREAMS> when you also want the task's streams (it returns { submit, run, streams, error, isLoading }).

5. Consume an AI/text stream (SDK 4.1.0+, recommended)

useRealtimeStream takes a defined stream for full type safety, or a runId plus optional stream key. Returns { parts, error }.

"use client";
import { useRealtimeStream } from "@trigger.dev/react-hooks";
import { aiStream } from "@/trigger/streams"; // a defined stream -> typed parts

export function StreamView({ runId, publicAccessToken }: { runId: string; publicAccessToken: string }) {
  const { parts, error } = useRealtimeStream(aiStream, runId, {
    accessToken: publicAccessToken,
    timeoutInSeconds: 300, // default 60
    onData: (chunk) => console.log(chunk),
  });
  if (error) return <div>Error: {error.message}</div>;
  if (!parts) return <div>Loading...</div>;
  return <div>{parts.join("")}</div>;
}

Without a defined stream: useRealtimeStream<string>(runId, "ai-output", { accessToken }), or omit the key to use the default stream. Other options: baseURL, startIndex, throttleInMs (default 16). The legacy useRealtimeRunWithStreams(runId, options) hook is still supported when you need both the run and all its streams at once.

6. Send input back into a running task

"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 })}>
      Approve
    </button>
  );
}

7. Complete a wait token from React

// backend: create the token, return id + publicAccessToken to the frontend
import { wait } from "@trigger.dev/sdk";
const token = await wait.createToken({ timeout: "10m" });
return { tokenId: token.id, publicToken: token.publicAccessToken };
"use client";
import { useWaitToken } from "@trigger.dev/react-hooks";

export function Approve({ tokenId, publicToken }: { tokenId: string; publicToken: string }) {
  const { complete } = useWaitToken(tokenId, { accessToken: publicToken });
  return <button onClick={() => complete({ approved: true })}>Approve</button>;
}

8. Subscribe from the backend (async iterators)

import { runs, tasks } from "@trigger.dev/sdk";
import type { myTask } from "./trigger/my-task";

const handle = await tasks.trigger("my-task", { some: "data" });
for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
  console.log(run.payload.some, run.output?.some); // typed
}

runs.subscribeToRun completes when the run finishes, so the loop exits on its own.

Common mistakes

  1. CRITICAL: Triggering from the browser with a Public Access Token. The read token from createPublicToken cannot trigger tasks.

    • Wrong: useTaskTrigger("my-task", { accessToken: publicAccessTokenFromCreatePublicToken })
    • Correct: mint a single-use Trigger Token with auth.createTriggerPublicToken("my-task") and pass that.
  2. Token with no scopes. A scopeless token authorizes nothing, so every subscribe 403s.

    • Wrong: await auth.createPublicToken()
    • Correct: await auth.createPublicToken({ scopes: { read: { runs: ["run_1234"] } } })
  3. Polling with useRun/SWR for live updates. useRun is the SWR-based management-API hook (not recommended for live state); set refreshInterval: 0 to stop polling if you do use it.

    • Wrong: useRun(runId, { refreshInterval: 1000 }) to track progress
    • Correct: useRealtimeRun(runId, { accessToken }) (no polling, no WebSocket setup)
  4. Forgetting "use client". Realtime/trigger hooks cannot run in a server component.

    • Wrong: a Next.js App Router server component using useRealtimeRun
    • Correct: put "use client"; at the top of any component using these hooks.
  5. Shipping payload/output you do not render.

    • Wrong: useRealtimeRun(runId, { accessToken }) for a status badge (large payloads over the wire)
    • Correct: useRealtimeRun(runId, { accessToken, skipColumns: ["payload", "output"] })
  6. Subscribing before the handle exists.

    • Wrong: useRealtimeRun(handle, { accessToken: handle?.publicAccessToken }) with no guard
    • Correct: add enabled: !!handle so it subscribes only once the trigger returns a handle.

References

Sibling skills:

  • trigger-tasks for the task side: streams.define(), metadata.set(), and wait.createToken.
  • trigger-authoring-chat-agent and trigger-chat-agent-advanced for chat agents, which build on these realtime streams.

Reference docs ship beside this skill in the same package, read them locally (no network), pinned to your installed version. The sources: frontmatter above lists every doc this skill draws from, all under @trigger.dev/sdk/docs/. Start with:

  • @trigger.dev/sdk/docs/realtime/react-hooks/subscribe.mdx
  • @trigger.dev/sdk/docs/realtime/react-hooks/streams.mdx
  • @trigger.dev/sdk/docs/realtime/auth.mdx
  • @trigger.dev/sdk/docs/realtime/run-object.mdx (the realtime run object differs from the management-API object returned by useRun)

Version

This skill is bundled inside @trigger.dev/sdk and read directly from node_modules, so it always matches your installed SDK version (see the adjacent package.json). The full documentation for these APIs ships alongside it under @trigger.dev/sdk/docs/.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The analyzed skill is safe and presents no security issues. It instructs an AI agent on how to use Trigger.dev's frontend SDK hooks and backend token minting for handling realtime runs, text/AI streams, and task triggering within web frameworks. The code snippets follow secure token patterns and warn developers against architectural mistakes like exposing excessive capabilities via tokens.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    2/2 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 43d4ee1. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 3 months ago
type
core
library
trigger.dev
Other metadata
sources
[
  "docs/realtime/overview.mdx",
  "docs/realtime/how-it-works.mdx",
  "docs/realtime/auth.mdx",
  "docs/realtime/run-object.mdx",
  "docs/realtime/react-hooks/overview.mdx",
  "docs/realtime/react-hooks/subscribe.mdx",
  "docs/realtime/react-hooks/triggering.mdx",
  "docs/realtime/react-hooks/streams.mdx",
  "docs/realtime/react-hooks/swr.mdx",
  "docs/realtime/react-hooks/use-wait-token.mdx",
  "docs/realtime/backend/subscribe.mdx"
]
  • TypeScript
  • trigger.dev
  • realtime
  • task-monitoring
  • react-hooks
  • streaming
  • progress-tracking
  • ai-responses

README badge

README badge for triggerdotdev/skills/trigger-realtime

Provides real-time subscriptions to Trigger.dev task runs from React and backend code, with hooks for displaying progress, streaming AI responses, and handling approvals. Use for building live dashboards, progress indicators, and interactive task monitoring in frontend applications.

Generated from the current SKILL.md.

Does this work with React and backend Node.js, or just one?
Both. The skill includes React hooks for frontend subscriptions and backend SDK methods for Node.js. You can trigger and monitor tasks from either environment.
How do I authenticate from the frontend without exposing my API key?
Create a public access token or trigger token on the backend with limited scope and expiration time, then pass that token to frontend hooks. The SKILL.md shows examples using `auth.createPublicToken()` and `auth.createTriggerPublicToken()`.
Can I stream AI responses (like OpenAI) to the browser in real-time?
Yes. Define a stream with `streams.define()`, pipe it in a task (e.g., from an OpenAI completion), and read it in React using `useRealtimeStream()`.
Does this support human approval workflows?
Yes, using wait tokens. Tasks can pause and wait for approval via `wait.forToken()`, and React can complete the token to resume the task.
What Trigger.dev SDK version does this require?
The SKILL.md does not specify a minimum version. Check your Trigger.dev project's package.json or the official docs for compatibility.

Generated from the current SKILL.md. These answers refresh after source changes.