/trigger-realtime-and-frontend

name: trigger-realtime-and-frontend
description: >
  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-authoring-tasks territory); this is the consumer side.
type: core
library: trigger.dev

Realtime and Frontend

The full, version-pinned reference ships **inside your installed `@trigger.dev/sdk`**. Read it before writing code — it always matches the SDK version in this project, so it never drifts:

• **Skill:** `node_modules/@trigger.dev/sdk/skills/trigger-realtime-and-frontend/SKILL.md` — run subscriptions, `@trigger.dev/react-hooks`, streams, frontend triggering, and scoped tokens.
• **Docs:** the full, version-pinned docs ship bundled at `node_modules/@trigger.dev/sdk/docs/realtime/`; the skill above lists the exact pages it draws from in its `sources:` frontmatter. Grep for a hook, e.g. `grep -rl "useRealtimeRun" node_modules/@trigger.dev/sdk/docs/`.

If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install it first. In a non-hoisted layout, resolve the package with `node -p "require.resolve('@trigger.dev/sdk/package.json')"` and read `skills/` + `docs/` beside it.

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-authoring-tasks** (the task side: `streams.define()`, `metadata.set()`, `wait.createToken`), **trigger-authoring-chat-agent** and **trigger-chat-agent-advanced** (chat agents build on these realtime streams).