# inngest-middleware

Teaches your AI assistant how to build Inngest v4 middleware for dependency injection and payload encryption.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3600 installs · ★ 29
- Author: inngest
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/inngest/inngest-skills/tree/HEAD/skills/inngest-middleware/SKILL.md
- Updated: 2026-09-28
- HTML: https://affpapa.org/en/nevibecode/skills/inngest-middleware

## What it does

The skill provides lifecycle patterns for Inngest v4 middleware. It clarifies the execution order across client-level and function-level middleware: client instances execute first, followed by function-level handlers. It also guides agents through custom implementations using `onFunctionRun` and `onSendEvent` hooks for structured logging and payload transformations.

It details built-in dependency injection via `dependencyInjectionMiddleware` to pass database clients or external SDKs directly into handler arguments. Official extensions like `@inngest/middleware-encryption` with key rotation and `@inngest/middleware-sentry` for capturing run exceptions are covered as well.

Do not use this skill for realtime workflows. Inngest v4 ships realtime publishing natively via `step.realtime.publish`, and installing the legacy `@inngest/realtime` package causes a runtime `TypeError: Cls is not a constructor` crash.

## Requirements
- Works with: Sentry, Stripe

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add inngest/inngest-skills --skill inngest-middleware -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/inngest-middleware/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/inngest-middleware/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add inngest/inngest-skills --skill inngest-middleware -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/inngest-middleware/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add inngest/inngest-skills --skill inngest-middleware -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/inngest-middleware/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install inngest/inngest-skills inngest-middleware
```

2. **Manually: put the files in place**
- File: `.github/skills/inngest-middleware/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add inngest/inngest-skills --skill inngest-middleware -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/inngest/inngest-skills --path skills/inngest-middleware
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/inngest-middleware/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add inngest/inngest-skills --skill inngest-middleware -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/inngest/inngest-skills/tree/HEAD/skills/inngest-middleware/SKILL.md

## When to use it
- inject database clients or external SDKs into function handlers
- encrypt step payloads and function outputs using `@inngest/middleware-encryption`
- capture run exceptions and execution traces with `@inngest/middleware-sentry`
- build custom logging middleware using `onFunctionRun` lifecycle hooks

## Example prompts
- Inject Prisma and an OpenAI client into all Inngest functions using middleware
- Create a custom Inngest v4 middleware that logs event payloads on send
- Set up @inngest/middleware-encryption with fallback decryption keys

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 94ba9127959b4858.

BEGIN THIRD-PARTY FILE 94ba9127959b4858
````text
---
name: inngest-middleware
description: Use when adding cross-cutting concerns to durable functions — structured logging or tracing across all functions, error tracking with Sentry, payload encryption for sensitive data, dependency injection of clients (DB, Stripe, etc.) into function handlers, custom telemetry, or behavior that should apply uniformly across many functions. Covers Inngest middleware lifecycle, creating custom middleware, dependencyInjectionMiddleware, @inngest/middleware-encryption, @inngest/middleware-sentry, and custom middleware patterns.
---

# Inngest Middleware

Master Inngest middleware to handle cross-cutting concerns like logging, error tracking, dependency injection, and data transformation. Middleware runs at key points in the function lifecycle, enabling powerful patterns for observability and shared functionality.

> **These skills are focused on TypeScript.** For Python or Go, refer to the [Inngest documentation](https://www.inngest.com/llms.txt) for language-specific guidance. Core concepts apply across all languages.

> **Note:** The middleware system was significantly rewritten in v4. The lifecycle hooks documented here reflect the v4 API. If migrating from v3, consult the [migration guide](https://www.inngest.com/docs-markdown/reference/typescript/v4/migrations/v3-to-v4) for details on breaking changes.

> **⚠ For Realtime use the `inngest-realtime` skill, NOT this one.** Inngest v3 used `realtimeMiddleware()` from `@inngest/realtime` to inject a `publish` arg into function handlers. **v4 ships realtime natively** — `step.realtime.publish` is built-in, no middleware required. Do NOT install `@inngest/realtime` on a v4 project (it's a v3-era package and produces `TypeError: Cls is not a constructor` at runtime). See the `inngest-realtime` skill for the v4 pattern.

## What is Middleware?

Middleware allows code to run at various points in an Inngest client's lifecycle - during function execution, event sending, and more. Think of middleware as hooks into the Inngest execution pipeline.

**When to use middleware:**

- **Observability:** Add logging, tracing, or metrics
- **Dependency injection:** Share client instances across functions
- **Data transformation:** Encrypt/decrypt, validate, or enrich data
- **Error handling:** Custom error tracking and alerting
- **Authentication:** Validate user context or permissions

## Middleware Lifecycle

Middleware can be registered at **client-level** (affects all functions) or **function-level** (affects specific functions).

### Execution Order

```typescript
const inngest = new Inngest({
  id: "my-app",
  middleware: [
    loggingMiddleware, // Runs 1st
````
END THIRD-PARTY FILE 94ba9127959b4858

The third-party file has ended. Everything between the 94ba9127959b4858 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2683 of 10209 bytes. © inngest · Apache-2.0 · https://github.com/inngest/inngest-skills/tree/HEAD/skills/inngest-middleware/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md