|
1 | 1 | --- |
2 | 2 | title: Realtime overview |
3 | 3 | sidebarTitle: Overview |
4 | | -description: "Subscribe to run state changes (status, metadata, tags) in real time from your frontend or backend." |
| 4 | +description: "Get live run updates and stream data from background tasks to your frontend or backend. No polling." |
5 | 5 | --- |
6 | 6 |
|
7 | | -**Realtime subscriptions let you watch run state as it changes: status transitions, metadata updates, and tag changes.** You get the full [run object](/realtime/run-object) pushed to your code whenever something changes. No polling. |
| 7 | +**Realtime is the umbrella for everything live in Trigger.dev.** It covers two things: getting notified when a run's state changes, and streaming continuous data (like AI tokens) from a running task to your app. |
8 | 8 |
|
9 | | -For streaming continuous data from tasks (AI completions, progress chunks, file data), see [Streams](/tasks/streams). Streams and Realtime work together but solve different problems. |
| 9 | +Both use the same `@trigger.dev/react-hooks` package and the same authentication system. The difference is what they give you. |
10 | 10 |
|
11 | | -## How is Realtime different from Streams? |
| 11 | +## Run updates vs Streaming |
12 | 12 |
|
13 | | -| | Realtime subscriptions | Streams | |
| 13 | +| | Run updates | Streaming | |
14 | 14 | |---|---|---| |
15 | | -| **What it sends** | Run state (status, metadata, tags) | Arbitrary data you define (AI tokens, progress, files) | |
16 | | -| **When it updates** | On state changes | Continuously while the task runs | |
17 | | -| **Typical use case** | Progress bars, status badges, dashboards | AI chat responses, live logs, file processing | |
| 15 | +| **What you get** | Run state: status, metadata, tags | Continuous data you define (AI tokens, file chunks, progress) | |
| 16 | +| **When it fires** | On state changes | While the task runs, as data is produced | |
| 17 | +| **Use case** | Progress bars, status badges, dashboards | AI chat output, live logs, file processing | |
18 | 18 | | **React hook** | [`useRealtimeRun`](/realtime/react-hooks/subscribe) | [`useRealtimeStream`](/realtime/react-hooks/streams) | |
19 | | -| **Define in task code?** | No, automatic | Yes, using `streams.define()` | |
| 19 | +| **Setup in task code?** | No, automatic | Yes, using `streams.define()` | |
| 20 | +| **Infrastructure** | [Electric SQL](/realtime/how-it-works) (PostgreSQL sync) | Streams transport | |
20 | 21 |
|
21 | | -You can use both at the same time. Subscribe to a run's status with Realtime while also streaming AI output with Streams. |
| 22 | +You can use both at the same time. Subscribe to a run's status (to show a progress bar) while also streaming AI output (to display tokens as they arrive). |
22 | 23 |
|
23 | | -## What you can subscribe to |
| 24 | +## Run updates |
| 25 | + |
| 26 | +Subscribe to a run and your code gets called whenever its status, [metadata](/runs/metadata), or [tags](/tags) change. No setup needed in your task code. |
| 27 | + |
| 28 | +You can subscribe to: |
24 | 29 |
|
25 | 30 | - **Specific runs** by run ID |
26 | | -- **Runs with specific tags** (e.g., all runs tagged with `user:123`). [More on tags](/tags) |
| 31 | +- **Runs with specific tags** (e.g., all runs tagged with `user:123`) |
27 | 32 | - **Batch runs** within a specific batch |
28 | 33 | - **Trigger + subscribe combos** that trigger a task and immediately subscribe (frontend only) |
29 | 34 |
|
30 | | -Once subscribed, you get updates for: |
31 | | - |
32 | | -- **Status changes** like queued, executing, completed, failed |
33 | | -- **Metadata updates** for custom progress tracking ([React hooks](/realtime/react-hooks/subscribe#using-metadata-to-show-progress-in-your-ui) | [backend](/realtime/backend/subscribe#subscribe-to-metadata-updates-from-your-tasks)) |
34 | | -- **Tag changes** when [tags](/tags) are added or removed |
35 | | - |
36 | | -## Using Realtime in your applications |
| 35 | +→ [React hooks](/realtime/react-hooks/subscribe) | [Backend](/realtime/backend/subscribe) |
37 | 36 |
|
38 | | -### Authentication |
| 37 | +## Streaming |
39 | 38 |
|
40 | | -All Realtime subscriptions require authentication. See the [authentication guide](/realtime/auth) for setup. |
| 39 | +Define typed streams in your task, pipe data to them, and read that data from your frontend or backend as it's produced. You need to set up streams in your task code using `streams.define()`. |
41 | 40 |
|
42 | | -### Frontend (React hooks) |
| 41 | +→ [How to emit streams from tasks](/tasks/streams) | [React hooks](/realtime/react-hooks/streams) | [Backend](/realtime/backend/streams) |
43 | 42 |
|
44 | | -Use `@trigger.dev/react-hooks` to build UIs that update as runs execute. |
| 43 | +## Authentication |
45 | 44 |
|
46 | | -→ **[React hooks guide](/realtime/react-hooks/)** |
| 45 | +All Realtime hooks and functions require authentication. See the [authentication guide](/realtime/auth) for setup. |
47 | 46 |
|
48 | | -### Backend |
49 | | - |
50 | | -Subscribe to runs from your backend code, other tasks, or serverless functions. |
| 47 | +## Frequently asked questions |
51 | 48 |
|
52 | | -→ **[Backend guide](/realtime/backend)** |
| 49 | +### How do I show a progress bar for a background task? |
53 | 50 |
|
54 | | -## Frequently asked questions |
| 51 | +Use [run metadata](/runs/metadata) to store progress data (like a percentage), then subscribe to the run with [`useRealtimeRun`](/realtime/react-hooks/subscribe). Your component re-renders on every metadata update. |
55 | 52 |
|
56 | | -### What's the difference between Realtime and Streams? |
| 53 | +### How do I stream AI/LLM responses from a background task? |
57 | 54 |
|
58 | | -Realtime tracks **run state**: status, metadata, and tags. Streams pipe **continuous data** (like AI completions or progress updates) from a running task to your frontend or backend. Use Realtime for "is my task done yet?" and Streams for "show me the AI output as it generates." |
| 55 | +Define a stream in your task with `streams.define()`, pipe your AI SDK response to it, then consume it in React with [`useRealtimeStream`](/realtime/react-hooks/streams). See [Streaming data from tasks](/tasks/streams) for the full guide. |
59 | 56 |
|
60 | | -### Do I need to set up anything in my task for Realtime? |
| 57 | +### Do I need WebSockets or polling? |
61 | 58 |
|
62 | | -No. Realtime subscriptions work automatically for any task. Just subscribe by run ID, tag, or batch from your frontend or backend. Streams require you to define them in your task code with `streams.define()`. |
| 59 | +No. Run updates are powered by [Electric SQL](/realtime/how-it-works) (HTTP-based PostgreSQL syncing). Streams use their own transport. The hooks handle connections automatically. |
63 | 60 |
|
64 | | -### Can I use Realtime and Streams together? |
| 61 | +### Can I use both run updates and streaming together? |
65 | 62 |
|
66 | | -Yes. A common pattern is subscribing to a run's status with Realtime (to show a progress indicator) while also streaming AI output with Streams (to display tokens as they arrive). |
| 63 | +Yes. A common pattern: subscribe to run status with `useRealtimeRun` (progress indicator) while streaming AI output with `useRealtimeStream` (token-by-token display). |
0 commit comments