docs: add Recipes section with 5 real-world workflow guides#1116
docs: add Recipes section with 5 real-world workflow guides#1116johnlindquist wants to merge 4 commits intomainfrom
Conversation
Adds a new Recipes documentation section with production-ready patterns for common workflow use cases, driven by usage data analysis: - Data Synchronization (100 teams, 369K runs) - Webhook Integrations (40 teams, 516K runs) - Data Ingestion & File Processing (23 teams, 1.1M runs) - Notifications & Email (58 teams, 288K runs) - Error Monitoring & Alerting (19 teams, 4.7M runs)
|
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests▲ Vercel Production (3 failed)astro (1 failed):
nextjs-turbopack (1 failed):
nitro (1 failed):
🌍 Community Worlds (45 failed)turso (45 failed):
Details by Category❌ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
Replace verbose polling/scheduling examples in error-monitoring and webhook-integrations recipes with shorter inline snippets that link to the canonical Scheduling & Cron foundations guide for depth.
pranaygp
left a comment
pranaygp
left a comment
There was a problem hiding this comment.
Thorough review of the recipes docs. Overall this is a solid addition — well-structured, consistent patterns, good use of idempotency keys and error handling throughout. A few issues below, most notably the broken links that the bot also flagged.
| } | ||
| ``` | ||
|
|
||
| `sleep()` is durable — if the workflow restarts during a sleep, it resumes when the original duration expires. For comprehensive scheduling patterns including cron-like dispatching, health checks, and graceful shutdown, see [Scheduling & Cron](/docs/foundations/scheduling). |
There was a problem hiding this comment.
Broken link: /docs/foundations/scheduling does not exist. The foundations section has no scheduling.mdx. Either link to an existing page (e.g., the sleep() API reference or common-patterns) or remove this sentence.
The vercel bot also flagged this.
| } | ||
| ``` | ||
|
|
||
| This uses the durable polling pattern — `sleep()` consumes no compute while waiting, and the workflow resumes at the correct time even after restarts. For more advanced scheduling patterns including consecutive failure tracking, graceful shutdown, and cron-like dispatching, see [Scheduling & Cron](/docs/foundations/scheduling). |
There was a problem hiding this comment.
Broken link: Same issue — /docs/foundations/scheduling doesn't exist. This is referenced in both this file and webhook-integrations.mdx.
| if (response.status === 429) { | ||
| // Rate limited - back off exponentially // [!code highlight] | ||
| throw new RetryableError("Rate limited", { // [!code highlight] | ||
| retryAfter: metadata.attempt ** 2 * 1000, // [!code highlight] |
There was a problem hiding this comment.
Incorrect retryAfter value type: metadata.attempt ** 2 * 1000 passes a raw number (milliseconds). Per RetryableErrorOptions, a bare number is interpreted as milliseconds, so 1000 = 1s, 4000 = 4s, 9000 = 9s. That's likely fine, but the inline comment says "back off exponentially" which might mislead readers into thinking it's seconds. Consider either:
- Using a duration string for clarity:
retryAfter: \${metadata.attempt ** 2}s`` - Or adding a comment clarifying the unit is milliseconds
| The workflow sleeps for real calendar time between sends. If the process restarts during a sleep, the workflow resumes at the correct point. Use [`FatalError`](/docs/api-reference/workflow/fatal-error) to skip retries for permanent failures like a missing email address. | ||
|
|
||
| <Callout type="info"> | ||
| Email sends are side effects. Use [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) to pass a stable `stepId` as an idempotency key to your email provider, as shown in `sendConfirmationEmail` above. This prevents duplicate emails on retry. See [Idempotency](/docs/foundations/idempotency) for more details. |
There was a problem hiding this comment.
Stale reference: The callout says "as shown in sendConfirmationEmail above", but sendConfirmationEmail is in the Contact Form Processing section further down the page, not above this callout. This callout is in the Email Onboarding Sequence section where none of the step functions use getStepMetadata() or stepId.
Either:
- Add an idempotency key to one of the onboarding step functions above to match the callout, or
- Rephrase to something like: "Use
getStepMetadata()to pass a stablestepIdas an idempotency key to your email provider to prevent duplicate emails on retry. See the Contact Form example below or the Idempotency guide."
| "use workflow"; // [!code highlight] | ||
|
|
||
| // Replace slashes to keep tokens URL-safe | ||
| const safeRepoName = repoName.replace("/", ":"); // [!code highlight] |
There was a problem hiding this comment.
Nit: repoName.replace("/", ":") only replaces the first occurrence. For org/repo this works, but if there's ever a nested path this would be a subtle bug. Consider replaceAll or noting this only handles owner/repo format.
Minor since this is illustrative, but worth being precise in docs.
| Each `fetchPrice` call is an independent step. If the API rate-limits the third symbol, the first two are already recorded and won't re-execute. The third step retries with exponential backoff until it succeeds or exhausts its retry budget. | ||
|
|
||
| <Callout type="info"> | ||
| The default retry limit is 3. Set `fetchPrice.maxRetries = 10` after the function declaration to allow more attempts for flaky APIs. See [Errors and Retries](/docs/foundations/errors-and-retries) for the full retry API. |
There was a problem hiding this comment.
Nit: "The default retry limit is 3" — to be precise, maxRetries = 3 means 4 total attempts (1 initial + 3 retries), per the existing errors-and-retries docs. Might be worth saying "The default is 3 retries (4 total attempts)" for consistency with the foundations page.
|
|
||
| if (contacts.length > 0) { | ||
| await upsertContacts(contacts); | ||
| cursor = new Date(); |
There was a problem hiding this comment.
Minor: cursor is updated to new Date() after upserting, but this captures the time after the upsert completes, not the time of the last fetched record. If there's clock drift or the upsert takes time, you could miss records updated during that window. In a real implementation you'd use the updatedAt from the last returned contact.
Since this is a recipe/illustration it's probably fine, but a brief comment noting this simplification might help readers avoid this pitfall in production.
|
|
||
| // The hook may not be registered yet — retry until it is | ||
| let delivered = false; | ||
| for (let i = 0; i < 5 && !delivered; i++) { |
There was a problem hiding this comment.
This retry loop for resumeHook is a practical pattern but a bit ugly for docs. The comment on line 164 explains the race well, and the callout below suggests createWebhook() as an alternative. Just flagging that this pattern could confuse readers — they might copy it verbatim. Consider adding a note that this is a simplification and production code should handle the !delivered case (e.g., return an error response).
| .map((b) => b.toString(16).padStart(2, "0")) | ||
| .join(""); | ||
|
|
||
| if (signature !== expected) { |
There was a problem hiding this comment.
The HMAC signature comparison uses string equality (signature !== expected) which is potentially vulnerable to timing attacks. For a security-sensitive operation like webhook signature verification, this should use crypto.timingSafeEqual (or crypto.subtle.timingSafeEqual where available). Since this is docs that people will copy, it's worth getting right.
| if (signature !== expected) { | |
| if (!crypto.subtle.timingSafeEqual) { | |
| // Node.js < 22 fallback | |
| const { timingSafeEqual } = await import("node:crypto"); | |
| if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { | |
| await request.respondWith(new Response("Unauthorized", { status: 401 })); | |
| throw new FatalError("Invalid GitHub webhook signature"); | |
| } | |
| } else if (signature !== expected) { |
Or more simply, just use crypto.timingSafeEqual from node:crypto since steps have full Node.js access:
import { timingSafeEqual } from "node:crypto";
// ...
if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
|
Closing — superseded by the cookbook work in #1564. The 5 recipes here (data-sync, webhook-integrations, data-ingestion, email-notifications, error-monitoring) are covered by the restructured cookbook's 4-category system (common patterns, agent patterns, integrations, advanced). The "Recipes" section name was retired in favor of "Cookbook" per team decision on March 31. |
2 participants
Summary
Adds a new Recipes documentation section with production-ready patterns for common workflow use cases. Each recipe was motivated by usage data analysis across 10 workflow categories.
New docs
Structure
docs/content/docs/recipes/index.mdx— section overview with Cardsdocs/content/docs/recipes/meta.json— navigation configmeta.jsonto include Recipes after AI AgentsTest plan