theoai-inngest_skill

Overview

This skill provides practical guidelines and best practices for building and maintaining Inngest workflows and functions. It focuses on correct step usage, serialization limits, event schemas, error handling, and performance patterns to help you write durable, observable, and efficient event-driven code. Use it to avoid common pitfalls and to design maintainable serverless stateful jobs.

How this skill works

The skill inspects Inngest function structure, step usage, event typing, and common anti-patterns, then recommends concrete changes: where to place non-deterministic code, how to serialize returns, and which step primitives to prefer. It highlights patterns for parallelism, fanout, and tracing while flagging issues like nested steps, oversized payloads, and missing Zod event schemas. It also advises on logging, retries, and when to use NonRetriableError.

When to use it

• Creating new Inngest functions or refactoring existing ones
• Designing or editing event schemas and return types
• Optimizing workflow performance, concurrency, or cost
• Troubleshooting orchestration, retries, or observability issues
• Writing long-running or AI-driven background jobs that must survive failures

Best practices

• Place non-deterministic operations (DB/API/randomness) inside step.run() to preserve determinism and correct retries
• Avoid nesting or passing step objects; treat each step as an independent HTTP-executed unit
• Keep serialized returns under 4MB and avoid returning complex functions or unserializable objects
• Prefer step.run() for visual traceability; use step.invoke() only when separate concurrency control is required
• Use Inngest step primitives (fetch, waitForEvent, delay, sleepUntil) instead of blocking loops; leverage Promise.all for parallel steps
• Type events and returns with Zod and use Inngest's logger instead of console.log

Example use cases

• A long-running invoice processing workflow split into durable steps with retries and observability
• An AI inference pipeline where each model call is a step.run() to ensure correct retries and metrics
• Fanout email dispatch: aggregate parallel send steps with Promise.all and use step.run() to keep traces grouped
• Webhook-driven order handling that types event payloads with Zod and returns compact serialized results
• A scheduled cleanup job that uses step.sleepUntil or step.delay instead of busy-wait loops