Theo Ai’s Inngest Guidelines and Best Practices

Comprehensive best practices and guidelines for creating, refactoring, and maintaining Inngest code – maintained by Theo Ai.

When to use

Use this skill when working with Inngest functions and anything Inngest related. This includes, but is not limited to:

• Creating new Inngest functions
• Editing existing Inngest functions
• Managing/editing or creating Inngest events
• Optimizing Inngest code
• Using Inngest built-in tools
• Troubleshooting Inngest-specific issues

Core Inngest concepts:

• Event-driven functions – trigger on events, schedules, or webhooks
• Durable execution – automatic retries, state preservation across failures
• Flow control – concurrency limits, rate limiting, debouncing, prioritization
• Observability – built-in logging, metrics, and tracing

Why use it: You write business logic as “step functions” and Inngest handles reliability, retries, and orchestration. Great for long-running processes, AI workflows, and background jobs that need to survive failures.

Instructions

On how to use step

• In Inngest functions, each step is executed as a separate HTTP request. To ensure efficient and correct execution, place any non-deterministic logic (such as DB calls, API calls, random number generators, etc) within a step.run() call.
• Think of each call to step as a separete, self-fulfilling, serverless-like function.
• Do not nest calls to step. The step object must never be nested.
• Do not send step as argument to function calls. Keep the use of step constrained within the Inngest function.
• Returns from calls to step are serialized and deserialized by Inngest’s infrastructure. This means that complex objects and functions cannot be returned by a call to step.
• Be cognizant of the fact that each call to step is a separate HTTP request and that this adds infrastructure and execution time overheads. With that said, prefer to create algorithms that smartly and efficiently combine functionality within single steps. In other words, try to avoid micro steps. On the other hand, be sensitive to steps that might block execution for too long and become operational bottlenecks. Find a balance.

On serialization caveats

• Serialized returns are also limited to 4MB so, do make sure that returns are within those limits.

On useful patterns

• Come up with algorithms that levarage Inngest’s primitives as much as possible. I.e. step.fetch() is better than calls to fetch directly; a busy-wait loop can probably leverage step.waitForEvent(), step.sleept(), step.sleepUntil(), step.delay(), etc depending on the scenario
• When breaking down functionality, prefer step.run() over step.invoke() when possible, as the former allows fanout operations to be aggregated and visualized under the same function call in the Inngest WebUI, improving traceability. However, consider step.invoke() when you specifically need independent concurrency control, as inline step.run() calls cannot have their own concurrency limits separate from the parent function.
• In situations where multiple steps can run in parallel, utilize a Promise.all resolution.

On events schemas

• Make sure to always type the events and returns using the Zod infrastructure in place.

On Error-handling and debugging

• Be attentive of when to use NonRetriableError
• When utilizing and event/response pattern, make sure to return events in case of failure and treat them at the waiting side accordingly.
• When logging, use Inngest’s logger and not console.log

On anything else

• Refer to Inngest’s documentation (feel free to search the web extensivelly and/or fetch from https://www.inngest.com/docs ) for anything else you need

Anti-patterns to avoid

• Not using Steps
• Not typing events
• Nested steps
• Huge event payloads (must be 4MB or less)
• Ignoring concurrency