home / skills / get-theo-ai / agent-skills / theoai-inngest

theoai-inngest skill

This skill helps you develop, optimize, and troubleshoot Inngest workflows with best practices for events, steps, error handling, and observability.

npx playbooks add skill get-theo-ai/agent-skills --skill theoai-inngest

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

4.3 KB

---
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

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

FAQ

Why must non-deterministic logic live inside step.run()?

Each step executes as a separate HTTP request and may be retried; placing non-deterministic calls inside step.run() ensures the step’s inputs and behavior are captured and retried deterministically by Inngest.

When should I use step.invoke() instead of step.run()?

Use step.invoke() when you need independent concurrency limits or separate operational control for a subtask; prefer step.run() for better aggregation and visualization under the parent function.