---
name: theo-inngest
description: Inngest is a serverless event-driven workflow orchestration platform. It lets you build durable, stateful background jobs and workflows without managing infrastructure. Use this skill when working with Inngest functions, events, schemas, testing, or anything else Inngest-related.
metadata:
  author: "Theo Ai"
  version: "1.0.0"
---

# 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