trigger-realtime-and-frontend

Puts a background job's progress on the screen while it is still happening — a status that updates itself, text arriving word by word as a model writes it, and a button that starts a job straight from the page.

WHEN TO USE

SCOPE

USE FOR

Show a live-updating status badge or progress bar for a run.
Stream an AI model's output into the UI as it's generated.
Let a user trigger a task directly from a browser button.
Send input back into a task that is already running.

NOT FOR

Defining the backend task, its streams, or wait tokens — that's the trigger-authoring-tasks skill.
Building the chat agent itself — that's trigger-authoring-chat-agent or trigger-chat-agent-advanced.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (6)

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

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.
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"] } } })
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)
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.
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"] })
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-authoring-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/.

Local tool required

1 FOR THE AGENT

01
Install the React hooks package
Add @trigger.dev/react-hooks to your frontend app; the backend side already depends on @trigger.dev/sdk.

Not standalone. This skill ships with triggerdotdev/trigger.dev and only works together with that tool — install the tool first, then add this skill.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add https://github.com/triggerdotdev/trigger.dev/tree/main/packages/trigger-sdk/skills/trigger-realtime-and-frontend

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub

Same repository

trigger-authoring-chat-agent
Author and run a durable AI chat agent with chat.agent from @trigger.dev/sdk/ai: the per-turn run loop, why you MUST take streamText from the run argument rather than importing it from ai, returning a StreamTextResult vs calling chat.pipe(), the two server actions (chat.createStartSessionAction + auth.createPublicToken), and wiring useChat to useTriggerChatTransport. Load this when building, modifying, or debugging a chat backend (the agent task or its lifecycle hooks) or its React transport, when declaring typed tools or custom data parts, or when migrating a plain AI SDK streamText route to chat.agent.Read full description
trigger-authoring-tasks
Covers writing backend Trigger.dev tasks with @trigger.dev/sdk: defining task() and schemaTask(), the run function and its ctx, retries, waits, queues and concurrency, idempotency keys, run metadata, logging, triggering other tasks (and the Result shape), scheduled/cron tasks, and the essentials of trigger.config.ts. Load this whenever you are authoring or editing code inside a /trigger directory, defining a task, or writing backend code that triggers tasks. Realtime/React hooks and AI chat are covered by separate skills.Read full description
trigger-chat-agent-advanced
Advanced and operational chat.agent capabilities for Trigger.dev, loaded on demand. Load this when working on the raw Sessions primitive (sessions / SessionHandle), a custom chat transport or the realtime wire protocol, durable sub-agents (AgentChat, chat.stream.writer), human-in-the-loop, steering, actions, background injection (chat.defer / chat.inject), fast starts (preload, Head Start via @trigger.dev/sdk/chat-server), context resilience (compaction, recovery boot, OOM, large payloads), chat.local run-scoped state, offline testing with mockChatAgent, or prerelease/version upgrades. For the everyday chat.agent({...}) definition and the useTriggerChatTransport happy path, use the trigger-authoring-chat-agent skill instead.Read full description
trigger-dev-tasks
Use this skill when writing, designing, or optimizing Trigger.dev background tasks and workflows. This includes creating reliable async tasks, implementing AI workflows, setting up scheduled jobs, structuring complex task hierarchies with subtasks, configuring build extensions for tools like ffmpeg or Puppeteer/Playwright, and handling task schemas with Zod validation.Read full description
trigger-getting-started
Bootstrap Trigger.dev into an existing project from scratch: authenticate the CLI, install @trigger.dev/sdk and @trigger.dev/build, write trigger.config.ts with the project ref and task dirs, scaffold a /trigger directory with a first task, wire tsconfig and .gitignore, set TRIGGER_SECRET_KEY, and run the dev server. Load this when a project has no trigger.config.ts yet and the user asks to "add Trigger.dev", "set up Trigger.dev", "initialize Trigger.dev", or get a first task running, including in a monorepo. Once the project is set up and you are writing task code, switch to the trigger-authoring-tasks skill.Read full description

Realtime and Frontend

Setup

Core patterns

1. Subscribe to a run and render metadata progress

2. Status-only subscription with skipColumns

3. Trigger from the browser with a Trigger Token

4. Trigger and subscribe in one hook

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

6. Send input back into a running task

7. Complete a wait token from React

8. Subscribe from the backend (async iterators)

Common mistakes

References

Version

Local tool required

More skills

trigger-authoring-chat-agent

trigger-authoring-tasks

trigger-chat-agent-advanced

trigger-dev-tasks

trigger-getting-started

2. Status-only subscription with `skipColumns`