triggerdotdev · D-K-P · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026
diff --git a/docs/docs.json b/docs/docs.json
@@ -137,7 +137,7 @@
               "realtime/run-object",
               "realtime/auth",
               {
-                "group": "React hooks (frontend)",
+                "group": "React hooks",
                 "pages": [
                   "realtime/react-hooks/overview",
                   "realtime/react-hooks/triggering",
@@ -642,6 +642,10 @@
       "source": "/trigger-config",
       "destination": "/config/config-file"
     },
+    {
+      "source": "/guides/frameworks",
+      "destination": "/guides/frameworks/nextjs"
+    },
     {
       "source": "/guides/frameworks/introduction",
       "destination": "/guides/introduction"

diff --git a/docs/errors-retrying.mdx b/docs/errors-retrying.mdx
@@ -12,6 +12,8 @@ You can configure retrying in two ways:
 1. In your [trigger.config file](/config/config-file) you can set the default retrying behavior for all tasks.
 2. On each task you can set the retrying behavior.
 
+<Note>Task-level retry settings override the defaults in your `trigger.config` file.</Note>
+
 <Note>
   By default when you create your project using the CLI init command we disabled retrying in the DEV
   environment. You can enable it in your [trigger.config file](/config/config-file).

diff --git a/docs/guides/frameworks/nextjs.mdx b/docs/guides/frameworks/nextjs.mdx
@@ -45,7 +45,7 @@ For more information on authenticating with Trigger.dev, see the [API keys page]
 
 ## Triggering your task in Next.js
 
-Here are the steps to trigger your task in the Next.js App and Pages router and Server Actions. Alternatively, check out this repo for a [full working example](https://github.com/triggerdotdev/example-projects/tree/main/nextjs/server-actions/my-app) of a Next.js app with a Trigger.dev task triggered using a Server Action.
+Here are the steps to trigger your task in the Next.js App and Pages router and Server Actions.
 
 <Tabs>
 
@@ -432,5 +432,18 @@ You can test your revalidation task in the Trigger.dev dashboard on the testing
     <NextjsTroubleshootingMissingApiKey/>
     <NextjsTroubleshootingButtonSyntax/>
 
+## Realtime updates with React hooks
+
+The `@trigger.dev/react-hooks` package lets you subscribe to task runs from your React components. Show progress bars, stream AI responses, or display run status in real time.
+
+<CardGroup cols={2}>
+  <Card title="React hooks" icon="react" href="/realtime/react-hooks/overview">
+    Hooks for subscribing to runs, streaming data, and triggering tasks from the frontend.
+  </Card>
+  <Card title="Streams" icon="wave-pulse" href="/tasks/streams">
+    Pipe continuous data (like AI completions) from your tasks to the client while they run.
+  </Card>
+</CardGroup>
+
 <VercelDocsCards />
 <UsefulNextSteps />
diff --git a/docs/guides/frameworks/remix.mdx b/docs/guides/frameworks/remix.mdx
@@ -197,6 +197,19 @@ The `vercel-build` script in `package.json` is specific to Remix projects on Ver
 
 The `runtime: "edge"` configuration in the API route allows for better performance on Vercel's Edge Network.
 
+## Realtime updates with React hooks
+
+The `@trigger.dev/react-hooks` package lets you subscribe to task runs from your React components. Show progress bars, stream AI responses, or display run status in real time.
+
+<CardGroup cols={2}>
+  <Card title="React hooks" icon="react" href="/realtime/react-hooks/overview">
+    Hooks for subscribing to runs, streaming data, and triggering tasks from the frontend.
+  </Card>
+  <Card title="Streams" icon="wave-pulse" href="/tasks/streams">
+    Pipe continuous data (like AI completions) from your tasks to the client while they run.
+  </Card>
+</CardGroup>
+
 ## Additional resources for Remix
 
 <Card

diff --git a/docs/quick-start.mdx b/docs/quick-start.mdx
@@ -26,20 +26,30 @@ Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/open-
 
 </Steps>
 
+## Triggering tasks from your app
+
+The test page in the dashboard is great for verifying your task works. To trigger tasks from your own code, you'll need to set the `TRIGGER_SECRET_KEY` environment variable. Grab it from the API Keys page in the dashboard and add it to your `.env` file.
+
+```bash .env
+TRIGGER_SECRET_KEY=tr_dev_...
+```
+
+See [Triggering](/triggering) for the full guide, or jump straight to framework-specific setup for [Next.js](/guides/frameworks/nextjs), [Remix](/guides/frameworks/remix), or [Node.js](/guides/frameworks/nodejs).
+
 ## Next steps
 
 <CardGroup cols={2}>
 <Card title="Building with AI" icon="brain" href="/building-with-ai">
-  Learn how to build Trigger.dev projects using AI coding assistants
+  Build Trigger.dev projects using AI coding assistants
 </Card>
   <Card title="How to trigger your tasks" icon="bolt" href="/triggering">
-    Learn how to trigger tasks from your code.
+    Trigger tasks from your backend code
   </Card>
   <Card title="Writing tasks" icon="wand-magic-sparkles" href="/tasks/overview">
-    Tasks are the core of Trigger.dev. Learn what they are and how to write them.
+    Task options, lifecycle hooks, retries, and queues
   </Card>
   <Card title="Guides and example projects" icon="books" href="/guides/introduction">
-  Guides and examples for triggering tasks from your code.
+  Framework guides and working example repos
 </Card>
 
 </CardGroup>
diff --git a/docs/realtime/backend/overview.mdx b/docs/realtime/backend/overview.mdx
@@ -1,23 +1,22 @@
 ---
-title: Backend overview
+title: "Subscribe to tasks from your backend"
 sidebarTitle: Overview
-description: Using the Trigger.dev realtime API from your backend code
+description: "Subscribe to run progress, stream AI output, and react to task status changes from your backend code or other tasks."
 ---
 
 import RealtimeExamplesCards from "/snippets/realtime-examples-cards.mdx";
 
-Use these backend functions to subscribe to runs and streams from your server-side code or other tasks.
+**Subscribe to runs from your server-side code or other tasks using async iterators.** Get status updates, metadata changes, and streamed data without polling.
 
-## Overview
+## What's available
 
-There are three main categories of functionality:
-
-- **[Subscribe functions](/realtime/backend/subscribe)** - Subscribe to run updates using async iterators
-- **[Metadata](/realtime/backend/subscribe#subscribe-to-metadata-updates-from-your-tasks)** - Update and subscribe to run metadata in real-time
-- **[Streams](/realtime/backend/streams)** - Read and consume real-time streaming data from your tasks
+| Category | What it does | Guide |
+|---|---|---|
+| **Run updates** | Subscribe to run status, metadata, and tag changes | [Run updates](/realtime/backend/subscribe) |
+| **Streaming** | Read AI output, file chunks, or any continuous data from tasks | [Streaming](/realtime/backend/streams) |
 
 <Note>
-  To learn how to emit streams from your tasks, see our [Realtime Streams](/tasks/streams) documentation.
+  To learn how to emit streams from your tasks, see [Streaming data from tasks](/tasks/streams).
 </Note>
 
 ## Authentication

diff --git a/docs/realtime/backend/streams.mdx b/docs/realtime/backend/streams.mdx
@@ -1,13 +1,13 @@
 ---
-title: Streams
-sidebarTitle: Streams
-description: Read and consume real-time streaming data from your tasks in your backend
+title: "Stream data to your backend (AI, files)"
+sidebarTitle: "Streaming"
+description: "Read AI/LLM output, file chunks, and other streaming data from your Trigger.dev tasks in backend code."
 ---
 
-The Streams API allows you to read streaming data from your Trigger.dev tasks in your backend code. This is particularly useful for consuming AI/LLM outputs, progress updates, or any other real-time data that your tasks emit.
+**Read streaming data from your tasks in backend code.** Consume AI completions as they generate, process file chunks, or handle any continuous data your tasks produce.
 
 <Note>
-  To learn how to emit streams from your tasks, see our [Realtime Streams](/tasks/streams) documentation. For frontend applications using React, see our [React hooks streams documentation](/realtime/react-hooks/streams).
+  To emit streams from your tasks, see [Streaming data from tasks](/tasks/streams). For React components, see [Streaming in React](/realtime/react-hooks/streams).
 </Note>
 
 ## Reading streams

diff --git a/docs/realtime/backend/subscribe.mdx b/docs/realtime/backend/subscribe.mdx
@@ -1,10 +1,10 @@
 ---
-title: Subscribe functions
-sidebarTitle: Subscribe
-description: Subscribe to run updates using async iterators
+title: "Run updates (backend)"
+sidebarTitle: "Run updates"
+description: "Subscribe to run status changes, metadata updates, and tag changes from your backend code using async iterators."
 ---
 
-These functions allow you to subscribe to run updates from your backend code. Each function returns an async iterator that yields run objects as they change.
+**Subscribe to runs from your backend and get updates whenever status, metadata, or tags change.** Each function returns an async iterator that yields the run object on every change.
 
 ## runs.subscribeToRun
 

diff --git a/docs/realtime/how-it-works.mdx b/docs/realtime/how-it-works.mdx
@@ -1,12 +1,14 @@
 ---
-title: How it works
-sidebarTitle: How it works
-description: Technical details about how the Trigger.dev Realtime API works
+title: "How Realtime works"
+sidebarTitle: "How it works"
+description: "Technical architecture behind Trigger.dev's real-time run updates, built on Electric SQL and PostgreSQL syncing."
 ---
 
+This page covers the infrastructure behind **run updates** (status, metadata, tags). [Streaming](/tasks/streams) uses a separate transport.
+
 ## Architecture
 
-The Realtime API is built on top of [Electric SQL](https://electric-sql.com/), an open-source PostgreSQL syncing engine. The Trigger.dev API wraps Electric SQL and provides a simple API to subscribe to [runs](/runs) and get real-time updates.
+The run updates system is built on top of [Electric SQL](https://electric-sql.com/), an open-source PostgreSQL syncing engine. The Trigger.dev API wraps Electric SQL and provides a simple API to subscribe to [runs](/runs) and get updates as they happen.
 
 ## Run changes
 

diff --git a/docs/realtime/overview.mdx b/docs/realtime/overview.mdx
@@ -1,39 +1,63 @@
 ---
 title: Realtime overview
 sidebarTitle: Overview
-description: Using the Trigger.dev Realtime API to trigger and/or subscribe to runs in real-time.
+description: "Get live run updates and stream data from background tasks to your frontend or backend. No polling."
 ---
 
-Trigger.dev Realtime allows you to trigger, subscribe to, and get real-time updates for runs. This is useful for monitoring runs, updating UIs, and building real-time dashboards.
+**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.
 
-You can subscribe to real-time updates for different scopes of runs:
+Both use the same `@trigger.dev/react-hooks` package and the same authentication system. The difference is what they give you.
 
-- **Specific runs** - Monitor individual run progress by run ID
-- **Runs with specific tags** - Track all runs that have certain [tags](/tags) (e.g., all runs tagged with `user:123`)
-- **Batch runs** - All runs within a specific batch
-- **Trigger + subscribe combos** - Trigger a task and immediately subscribe to its run (frontend only)
+## Run updates vs Streaming
 
-Once subscribed, you'll receive the complete [run object](/realtime/run-object) with automatic real-time updates whenever the [run changes](/realtime/how-it-works#run-changes), including:
+| | Run updates | Streaming |
+|---|---|---|
+| **What you get** | Run state: status, metadata, tags | Continuous data you define (AI tokens, file chunks, progress) |
+| **When it fires** | On state changes | While the task runs, as data is produced |
+| **Use case** | Progress bars, status badges, dashboards | AI chat output, live logs, file processing |
+| **React hook** | [`useRealtimeRun`](/realtime/react-hooks/subscribe) | [`useRealtimeStream`](/realtime/react-hooks/streams) |
+| **Setup in task code?** | No, automatic | Yes, using `streams.define()` |
+| **Infrastructure** | [Electric SQL](/realtime/how-it-works) (PostgreSQL sync) | Streams transport |
 
-- **Status changes** - queued → executing → completed, etc.
-- **Metadata updates** - Custom progress tracking, status updates, user data, etc. ([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))
-- **Tag changes** - When [tags](/tags) are added or removed from the run
-- **Realtime Streams** - Stream real-time data from your tasks, perfect for AI/LLM outputs and progress updates. ([Learn more](/tasks/streams) | [React hooks](/realtime/react-hooks/streams) | [Backend](/realtime/backend/streams))
+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).
 
-## Using Realtime in your applications
+## Run updates
 
-### Authentication
+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.
 
-All Realtime subscriptions require authentication so you can securely trigger and subscribe to runs. See our [authentication guide](/realtime/auth) for more details.
+You can subscribe to:
 
-### Frontend implementation
+- **Specific runs** by run ID
+- **Runs with specific tags** (e.g., all runs tagged with `user:123`)
+- **Batch runs** within a specific batch
+- **Trigger + subscribe combos** that trigger a task and immediately subscribe (frontend only)
 
-Use our React hooks to build real-time UIs that update as runs execute. Ideal for progress bars, status indicators, and live dashboards.
+→ [React hooks](/realtime/react-hooks/subscribe) | [Backend](/realtime/backend/subscribe)
 
-→ **[See our React hooks guide](/realtime/react-hooks/)**
+## Streaming
 
-### Backend implementation
+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()`.
 
-Use our server-side SDK to subscribe to runs from your backend code, other tasks, or serverless functions. Perfect for triggering workflows, sending notifications, or updating databases based on run status changes.
+→ [How to emit streams from tasks](/tasks/streams) | [React hooks](/realtime/react-hooks/streams) | [Backend](/realtime/backend/streams)
 
-→ **[See our Backend guide](/realtime/backend)**
+## Authentication
+
+All Realtime hooks and functions require authentication. See the [authentication guide](/realtime/auth) for setup.
+
+## Frequently asked questions
+
+### How do I show a progress bar for a background task?
+
+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.
+
+### How do I stream AI/LLM responses from a background task?
+
+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.
+
+### Do I need WebSockets or polling?
+
+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.
+
+### Can I use both run updates and streaming together?
+
+Yes. A common pattern: subscribe to run status with `useRealtimeRun` (progress indicator) while streaming AI output with `useRealtimeStream` (token-by-token display).
diff --git a/docs/realtime/react-hooks/overview.mdx b/docs/realtime/react-hooks/overview.mdx
@@ -1,12 +1,12 @@
 ---
-title: React hooks overview
+title: "React hooks for real-time task updates"
 sidebarTitle: Overview
-description: Using the Trigger.dev Realtime API from your React applications.
+description: "Subscribe to background task progress, stream AI responses, and trigger tasks from React components using @trigger.dev/react-hooks."
 ---
 
 import RealtimeExamplesCards from "/snippets/realtime-examples-cards.mdx";
 
-Our React hooks package provides a set of hooks that make it easy to interact with the Trigger.dev Realtime API from your React applications. You can use these hooks to subscribe to real-time updates, and trigger tasks from your frontend.
+**`@trigger.dev/react-hooks` gives your React components live access to background tasks.** Subscribe to run progress, stream AI output as it generates, or trigger tasks directly from the browser.
 
 ## Installation
 
@@ -55,19 +55,19 @@ Learn more about [generating and managing tokens in our authentication guide](/r
 
 ## Available hooks
 
-We provide several categories of hooks:
-
-- **[Triggering hooks](/realtime/react-hooks/triggering)** - Trigger tasks from your frontend application
-- **[Subscribe hooks](/realtime/react-hooks/subscribe)** - Subscribe to runs, batches, metadata, and more
-- **[Streams hooks](/realtime/react-hooks/streams)** - Subscribe to real-time streams from your tasks
-- **[SWR hooks](/realtime/react-hooks/swr)** - Fetch data once and cache it using SWR
+| Hook category | What it does | Guide |
+|---|---|---|
+| **Trigger hooks** | Trigger tasks from the browser | [Triggering](/realtime/react-hooks/triggering) |
+| **Run updates** | Subscribe to run status, metadata, and tags | [Run updates](/realtime/react-hooks/subscribe) |
+| **Streaming** | Consume AI output, file chunks, or any continuous data | [Streaming](/realtime/react-hooks/streams) |
+| **SWR hooks** | One-time fetch with caching (not recommended for most cases) | [SWR](/realtime/react-hooks/swr) |
 
 ## SWR vs Realtime hooks
 
-We offer two "styles" of hooks: SWR and Realtime. The SWR hooks use the [swr](https://swr.vercel.app/) library to fetch data once and cache it. The Realtime hooks use [Trigger.dev Realtime](/realtime) to subscribe to updates in real-time.
+We offer two "styles" of hooks: SWR and Realtime. SWR hooks use the [swr](https://swr.vercel.app/) library to fetch data once and cache it. Realtime hooks use [Trigger.dev Realtime](/realtime) to subscribe to updates as they happen.
 
 <Note>
   It can be a little confusing which one to use because [swr](https://swr.vercel.app/) can also be
   configured to poll for updates. But because of rate-limits and the way the Trigger.dev API works,
-  we recommend using the Realtime hooks for most use-cases.
+  we recommend using the Realtime hooks for most use cases.
 </Note>