Restructured the realtime docs #2317
Conversation
|
WalkthroughThis change reorganizes and expands the documentation structure for the Trigger.dev Realtime API. The navigation in Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🔭 Outside diff range comments (1)
docs/realtime/react-hooks/triggering.mdx (1)
80-93: Early return short-circuits realtime updatesThe
if (handle) { return … }block renders immediately after a task is triggered, preventing the component from ever reaching the realtime subscription branch whererunis updated. A minimal re-ordering keeps the UI responsive while still showing progress.- if (handle) { - return <div>Run ID: {handle.id}</div>; - } - - if (realtimeError) { + if (realtimeError) { return <div>Error: {realtimeError.message}</div>; } - if (run) { - return <div>Run ID: {run.id}</div>; - } + if (run) { + return <div>Run ID: {run.id}</div>; + } + + if (handle) { + return <div>Run ID: {handle.id}</div>; + }
🧹 Nitpick comments (15)
docs/realtime/react-hooks/triggering.mdx (1)
189-189: Drop the stray{" "}The added JSX fragment renders an unnecessary space and clutters the markup.
-<RealtimeExamplesCards />{" "} +<RealtimeExamplesCards />docs/realtime/react-hooks/swr.mdx (1)
36-44: Add'use client';to the typed example for consistencyThe first example includes the directive but the typed version does not. Including it avoids confusion for readers using the Next.js App Router.
+"use client"; import { useRun } from "@trigger.dev/react-hooks"; import type { myTask } from "@/trigger/myTask";docs/realtime/react-hooks/overview.mdx (1)
25-27: Correct Yarn install command
yarn addis the canonical way to add a dependency;yarn installinstalls all existing deps.-```bash yarn -yarn install @trigger.dev/react-hooks +```bash yarn +yarn add @trigger.dev/react-hooksdocs/realtime/backend/subscribe.mdx (1)
31-37: Show a clean exit strategy for infinite iterators
subscribeToRunsWithTagnever completes, but the example omits a break mechanism. Demonstrating anAbortControlleror manualbreakmakes the pattern production-ready and prevents runaway loops.docs/realtime/backend/metadata.mdx (2)
11-15: Broken anchor in link – update target path
/realtime/react-hooks/realtime#using-metadatadoesn’t exist after the restructure (the page was renamed to/realtime/react-hooks/realtimeand the heading became## Using metadata). Either drop the#using-metadatafragment or confirm the section id still resolves.
222-223: Extraneous JSX fragment
{" "}after theRealtimeExamplesCardscomponent renders an empty text node and is unnecessary.-<RealtimeExamplesCards />{" "} +<RealtimeExamplesCards />docs/realtime/run-object.mdx (1)
55-60: Typo in enum description
it's maxDuration→its maxDuration.-| `TIMED_OUT` | Run has reached it's maxDuration and has been stopped | +| `TIMED_OUT` | Run has reached its maxDuration and has been stopped |docs/realtime/react-hooks/streams.mdx (1)
225-226: Superfluous spacing nodeSame JSX fragment issue as in the backend metadata doc.
-<RealtimeExamplesCards />{" "} +<RealtimeExamplesCards />docs/realtime/overview.mdx (1)
9-10: Minor grammar fix
allows you subscribe to runs→allows you to subscribe to runs.-Trigger.dev Realtime allows you subscribe to runs and get real-time updates as they execute. +Trigger.dev Realtime allows you to subscribe to runs and get real-time updates as they execute.docs/realtime/how-it-works.mdx (2)
47-66: Clarify generic-union syntax to avoid TypeScript parsing edge-casesThe union passed to
subscribeToRunsWithTagis technically valid but can confuse the TS parser or ESLint rules because the|has very low precedence inside a type argument list. Adding parentheses improves readability and eliminates any ambiguity.-for await (const run of runs.subscribeToRunsWithTag<typeof myTask | typeof myOtherTask>("my-tag")) { +for await (const run of runs.subscribeToRunsWithTag<(typeof myTask | typeof myOtherTask)>("my-tag")) {
89-92: Nit: tighten wording of the known-issue disclaimer“are stored in object store” → “are stored in object storage” reads more naturally.
-... that has a large payload or large output and are stored in object store instead of the database. +... that has a large payload or output stored in object storage instead of the database.docs/realtime/react-hooks/realtime.mdx (2)
180-184: Grammar fix – drop the extra article-The `useRealtimeBatch` hook allows you to subscribe to a batch of runs by its the batch ID. +The `useRealtimeBatch` hook allows you to subscribe to a batch of runs by its batch ID.
598-604: Minor readability improvementThere is a stray leading space after
<RealtimeExamplesCards />causing{" "}to be rendered in MDX/JSX output. Removing it avoids an empty text node.-<RealtimeExamplesCards />{" "} +<RealtimeExamplesCards />docs/realtime/auth.mdx (1)
18-34: Call out security best-practice for “no-scope” token exampleThe first example creates a token with zero scopes. Consider adding a one-line warning so readers do not mistakenly ship a useless (or worse, later broadened) token to production.
-const publicToken = await auth.createPublicToken(); // 👈 this public access token has no permissions, so is pretty useless! +// ⚠️ Creates a token with **no** permissions – useful only for demonstration. +const publicToken = await auth.createPublicToken();docs/realtime/backend/streams.mdx (1)
124-129: Node-compatibility footnote forTextDecoderStream
TextDecoderStreamis available only in Node ≥ 20 or in browsers. If users run tasks on older Node versions they will hit a runtimeReferenceError. A short note here (or in prerequisites) will prevent surprises.Suggestion:
> **Note** > `TextDecoderStream` requires Node 20+ or a global polyfill when running in earlier environments.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (20)
docs/docs.json(2 hunks)docs/frontend/react-hooks/overview.mdx(0 hunks)docs/frontend/react-hooks/realtime.mdx(0 hunks)docs/realtime/auth.mdx(3 hunks)docs/realtime/backend/metadata.mdx(1 hunks)docs/realtime/backend/overview.mdx(1 hunks)docs/realtime/backend/streams.mdx(13 hunks)docs/realtime/backend/subscribe.mdx(1 hunks)docs/realtime/how-it-works.mdx(1 hunks)docs/realtime/overview.mdx(1 hunks)docs/realtime/react-hooks.mdx(0 hunks)docs/realtime/react-hooks/overview.mdx(1 hunks)docs/realtime/react-hooks/realtime.mdx(1 hunks)docs/realtime/react-hooks/streams.mdx(1 hunks)docs/realtime/react-hooks/swr.mdx(1 hunks)docs/realtime/react-hooks/triggering.mdx(2 hunks)docs/realtime/run-object.mdx(1 hunks)docs/realtime/subscribe-to-batch.mdx(0 hunks)docs/realtime/subscribe-to-run.mdx(0 hunks)docs/realtime/subscribe-to-runs-with-tag.mdx(0 hunks)
💤 Files with no reviewable changes (6)
- docs/realtime/react-hooks.mdx
- docs/realtime/subscribe-to-runs-with-tag.mdx
- docs/realtime/subscribe-to-run.mdx
- docs/realtime/subscribe-to-batch.mdx
- docs/frontend/react-hooks/realtime.mdx
- docs/frontend/react-hooks/overview.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (3)
docs/realtime/react-hooks/triggering.mdx (1)
65-65: Verify that the anchor slug actually resolves
#userealtimerunmay not match the slug generated by Docusaurus/MDX (typically lower-case words separated by dashes, i.e.#use-realtime-run). A broken link here will silently 404.docs/realtime/backend/overview.mdx (1)
47-58: Double-check SDK callmetadata.streamThe snippet uses
metadata.stream("openai", openaiCompletion), but the public v3 SDK examples usually expose streaming throughstreams.*helpers, notmetadata. Ifmetadata.streamis indeed correct, ignore this; otherwise update to avoid confusing readers.docs/docs.json (1)
575-581: Redirect may point to an auth overview rather than to the React-hooks landing
"/frontend/overview"is redirected to"/realtime/auth".
If the intent was to send users to the new Realtime landing page, use"/realtime/overview"instead; otherwise verify the old page really belonged to authentication docs.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
docs/realtime/auth.mdx (4)
2-4: Unify “Realtime” vs “Real-time” terminologyAcross the docs we switch between “Realtime” (no hyphen) and “real-time” (hyphenated). Pick one spelling and stick to it in titles, sidebar entries, and body copy to avoid confusing users and to keep navigation search-friendly.
13-17: Wrap top-levelawaitin an async contextThe snippet uses
awaitat module top level, which only works in ESM contexts and can throw readers off. Wrapping the call in anasyncIIFE makes the example copy-paste-safe in both CJS and ESM projects.-import { auth } from "@trigger.dev/sdk/v3"; - -const publicToken = await auth.createPublicToken(); +import { auth } from "@trigger.dev/sdk/v3"; + +(async () => { + const publicToken = await auth.createPublicToken(); + // … +})();
106-123: Minor grammar + possessive fixLine 108: “Public Access Token's expire” → “Public Access Tokens expire”.
While touching this paragraph, consider trimming the long sentence that enumeratesjoseunits into a bullet list for easier scanning.
221-225: Call out Node version requirement forfor await…of
for await…ofon an async iterator requires Node 10+ and an ES2018 target. Adding a short note (“Requires Node 10+ / modern browsers”) prevents confusion for readers on older runtimes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (12)
docs/guides/example-projects/batch-llm-evaluator.mdx(1 hunks)docs/guides/example-projects/human-in-the-loop-workflow.mdx(1 hunks)docs/guides/example-projects/vercel-ai-sdk-deep-research.mdx(1 hunks)docs/guides/example-projects/vercel-ai-sdk-image-generator.mdx(2 hunks)docs/introduction.mdx(5 hunks)docs/management/authentication.mdx(2 hunks)docs/realtime/auth.mdx(3 hunks)docs/runs/metadata.mdx(1 hunks)docs/snippets/realtime-learn-more.mdx(1 hunks)docs/triggering.mdx(1 hunks)docs/video-walkthrough.mdx(1 hunks)docs/wait-for-token.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (11)
- docs/guides/example-projects/vercel-ai-sdk-image-generator.mdx
- docs/triggering.mdx
- docs/guides/example-projects/human-in-the-loop-workflow.mdx
- docs/runs/metadata.mdx
- docs/guides/example-projects/vercel-ai-sdk-deep-research.mdx
- docs/wait-for-token.mdx
- docs/video-walkthrough.mdx
- docs/snippets/realtime-learn-more.mdx
- docs/management/authentication.mdx
- docs/introduction.mdx
- docs/guides/example-projects/batch-llm-evaluator.mdx
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When using Realtime features, use the `runs.subscribeToRun`, `runs.subscribeToRunsWithTag`, and `runs.subscribeToBatch` APIs as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : You MUST use `@trigger.dev/sdk/v3` when writing Trigger.dev tasks.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : ALWAYS generate Trigger.dev tasks using the `task` function from `@trigger.dev/sdk/v3` and export them as shown in the correct pattern.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When triggering a task from backend code, use `tasks.trigger`, `tasks.batchTrigger`, or `tasks.triggerAndPoll` as shown in the examples.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When implementing schema tasks, use `schemaTask` from `@trigger.dev/sdk/v3` and validate payloads as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When implementing scheduled (cron) tasks, use `schedules.task` from `@trigger.dev/sdk/v3` and follow the shown patterns.
Learnt from: nicktrn
PR: triggerdotdev/trigger.dev#2155
File: docs/docs.json:179-183
Timestamp: 2025-06-06T16:54:23.316Z
Learning: In the docs.json configuration for the Trigger.dev documentation (Mintlify system), both "tags": ["v4"] and "tag": "v4" properties can be used together and work correctly, even though this behavior is undocumented and may not work in local development environments.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When using idempotency, use the `idempotencyKeys` API and `idempotencyKey`/`idempotencyKeyTTL` options as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : NEVER generate deprecated code patterns using `client.defineJob` and related deprecated APIs, as shown in the prohibited code block.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : The `run` function contains your task logic in Trigger.dev tasks.
docs/realtime/auth.mdx (11)
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When using Realtime features, use the runs.subscribeToRun, runs.subscribeToRunsWithTag, and runs.subscribeToBatch APIs as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : You MUST use @trigger.dev/sdk/v3 when writing Trigger.dev tasks.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When triggering a task from backend code, use tasks.trigger, tasks.batchTrigger, or tasks.triggerAndPoll as shown in the examples.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When implementing schema tasks, use schemaTask from @trigger.dev/sdk/v3 and validate payloads as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When implementing scheduled (cron) tasks, use schedules.task from @trigger.dev/sdk/v3 and follow the shown patterns.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When using lifecycle hooks (init, cleanup, onStart, onSuccess, onFailure, handleError), implement them as shown in the examples for Trigger.dev tasks.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : ALWAYS generate Trigger.dev tasks using the task function from @trigger.dev/sdk/v3 and export them as shown in the correct pattern.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When using idempotency, use the idempotencyKeys API and idempotencyKey/idempotencyKeyTTL options as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : The run function contains your task logic in Trigger.dev tasks.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When using metadata in tasks, use the metadata API as shown, and only inside run functions or task lifecycle hooks.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to /trigger//*.{ts,tsx,js,jsx} : When triggering a task from inside another task, use yourTask.trigger, yourTask.batchTrigger, yourTask.triggerAndWait, yourTask.batchTriggerAndWait, batch.triggerAndWait, batch.triggerByTask, or batch.triggerByTaskAndWait as shown.
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (1)
docs/realtime/auth.mdx (1)
139-152: Verifytasks.triggerparameter orderingThe example passes four positional arguments:
tasks.trigger("my-task", payload, { tags }, { publicAccessToken: { … } })Current SDK (
@trigger.dev/sdk/v3) exposestasks.trigger(taskId, payload, options?), whereoptionsalready contains bothtagsandpublicAccessToken. If that’s still the case, the snippet will not compile.Please cross-check the live signature and update the example (or mention the breaking change) before publishing.
No description provided.