inngest-nextjs-patterns — Claude Code skill: Inngest in Next.js
inngest-nextjs-patterns — a template pack for Inngest background work in a Next.js App Router project: the client, the /api/inngest handler, typed events, cron jobs and fan-out functions.
MIT 141 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a claude-codeWhat inngest-nextjs-patterns does
The skill gives the agent ready-made shapes for durable background work on Inngest in a Next.js App Router codebase. It covers the singleton client, the route Inngest calls at /api/inngest, event definitions with Zod schemas, event-triggered functions, cron jobs with a timezone, and orchestrators that either fire work onward with step.sendEvent or wait on step.invoke.
Templates ship as separate files, each headed by a table of parameters the agent fills in; output lands at paths like src/inngest/functions/{name}.ts. A new function also has to go into src/inngest/functions/index.ts, since that array is what the route handler reads. A conventions document explains the naming rule for events (domain/entity.verb_past), why function ids stay kebab-case, and what makes a step safe to retry.
Projects without src/, or on the Pages Router, change the target paths in config.json; the defaults assume src/. Local runs need npx inngest-cli@latest dev plus INNGEST_DEV=1 in .env.local so the SDK points at the dev server on http://localhost:8288. Treat the function id as permanent: Inngest keys durable state on it, so renaming after a deploy strands the runs already recorded.
What it helps with
- add a background job to an existing App Router app
- define a typed event that producers send and workers consume
- schedule a recurring task on a cron expression with a timezone
- fan one event out to several workers and collect their results
- audit old Inngest functions for unstable ids and non-idempotent steps
Example prompts for the agent
- Add a background job that sends the receipt after checkout, using Inngest steps.
- Create a
shop/order.placedevent with a Zod schema and a function that reacts to it. - Wire up a cron function that clears stale drafts every hour.
How to install inngest-nextjs-patterns
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a claude-code2Manually: put the files in place
~/.claude/skills/inngest-nextjs-patterns/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/inngest-nextjs-patterns/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a codex2Manually: put the files in place
.agents/skills/inngest-nextjs-patterns/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a cursor2Manually: put the files in place
.cursor/skills/inngest-nextjs-patterns/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/inngest-nextjs-patterns2Manually: put the files in place
.github/skills/inngest-nextjs-patterns/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/inngest-nextjs-patternsManually: put the files in place
.devin/skills/inngest-nextjs-patterns/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about inngest-nextjs-patterns
How do I install inngest-nextjs-patterns in Claude Code?
Run npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a claude-code. The skill then sits at ~/.claude/skills/inngest-nextjs-patterns/SKILL.md.
What does inngest-nextjs-patterns do?
It hands the agent templates and conventions for Inngest in a Next.js App Router app: the client, the /api/inngest route, typed events, and durable functions with steps.
Why must the function id stay the same?
Inngest uses that id as the key for durable state. Rename it and the recorded runs no longer line up with the function.
Source text
SKILL.md · MIT
---
name: inngest-nextjs-patterns
description: Inngest event-driven functions in a Next.js (App Router) project — creating the client, the /api/inngest route handler, typed events with Zod schemas, durable event-triggered functions, scheduled cron functions, or fan-out orchestrators. Trigger when scaffolding Inngest patterns — and even if the user just says "add a background job", "process this async", "schedule X every hour", or "send an event when Y happens" in a Next.js codebase. Also trigger when reviewing existing Inngest code to enforce event-naming, function-id stability, and step-idempotency conventions.
---
# Inngest + Next.js Patterns
Templates and conventions for building event-driven, durable background work on Inngest from a Next.js App Router project. The skill enforces the conventions Inngest's own docs use (decentralized `eventType()` schemas, kebab-case stable function IDs, idempotent steps) so that retries, replays, and concurrency controls actually do what they advertise.
## When to Apply
Read this skill when you are:
- Setting up Inngest in a Next.js app for the first time (client + route handler + first function)
- Adding a new background job, webhook handler, or scheduled task to a Next.js app
- Defining a new domain event that other functions will trigger on
- Orchestrating multi-step work that must survive process restarts (durable workflows, sagas)
- Reviewing existing Inngest code for event naming, step idempotency, or stable function IDs
- Migrating from `setTimeout` / a queue library / a cron service to Inngest's durable execution model
## How to Use
1. **First time in this codebase?** Read [`references/conventions.md`](references/conventions.md) before writing anything. The conventions explain *why* event names take a specific shape, why function IDs must be stable, and why every `step.run` must be idempotent — once you understand the reasoning, the templates make sense.
2. **Pick a template** from the catalog below based on what you're creating.
3. **Render it** by substituting the documented parameters. Each template has a parameter table at the top of its file.
4. **Wire it up:** new functions must be added to `src/inngest/functions/index.ts` (the registry the route handler reads). The conventions doc shows the registry pattern.
## Available Templates
| Template | Output Path | Use When |
|---|---|---|
| [`client.ts.template`](assets/templates/client.ts.template) | `src/inngest/client.ts` | One-time setup: create the singleton Inngest client. Generate **once per app**. |
| [`route-handler.ts.template`](assets/templates/route-handler.ts.template) | `src/app/api/inngest/route.ts` | One-time setup: the App Router endpoint Inngest hits to invoke your functions. Generate **once per app**. |
| [`event.ts.template`](assets/templates/event.ts.template) | `src/inngest/events/{domain}.ts` | Defining a new typed event (with Zod schema) that producers send and functions consume. |
| [`function.ts.template`](assets/templates/function.ts.template) | `src/inngest/functions/{name}.ts` | Standard event-triggered durable function with steps. Parameterized retries, concurrency, throttle, debounce, cancelOn, onFailure. |
| [`function-cron.ts.template`](assets/templates/function-cron.ts.template) | `src/inngest/functions/{name}.ts` | Scheduled function — runs on a cron expression (with timezone). Optionally also accepts a manual event trigger for ad-hoc invocation. |
| [`function-fan-out.ts.template`](assets/templates/function-fan-out.ts.template) | `src/inngest/functions/{name}.ts` | Orchestrator that receives one event and fans out work — via `step.sendEvent` (fire-and-forget) or `Promise.all(step.invoke(...))` (wait for results). |
## Quick Reference
- **Event name shape:** `domain/entity.verb_past` — e.g., `app/user.created`, `shop/order.placed`, `billing/invoice.paid`. The conventions doc has the full rule.
- **Function `id`:** stable kebab-case, **never rename it** after deploy — Inngest uses it as the durable state key.
- **Step `id`:** descriptive kebab-case, also durable; changing one re-runs that step on replay.
- **Idempotency:** every `step.run` must be safely retryable. If it calls a third-party API that mutates state, pass an idempotency key.
- **Dev server:** `npx inngest-cli@latest dev`, then UI at http://localhost:8288. Set `INNGEST_DEV=1` in `.env.local` to point the SDK at it.
## Project Layout Assumption
Templates assume a `src/` directory with App Router:
```
src/
├── app/api/inngest/route.ts # generated by route-handler template
└── inngest/
├── client.ts # generated by client template
├── events/ # one file per domain (events.shop.ts, events.user.ts)
│ └── {domain}.ts # generated by event template
└── functions/
├── index.ts # registry: re-exports all functions as an array
└── {name}.ts # generated by function/cron/fan-out templates
```
If your project uses a different layout (no `src/`, or Pages Router), override the output paths in `config.json`. The conventions doc explains the trade-offs.
## Setup
`config.json` controls path overrides. On first use, check whether its fields are filled in — if not, ask the user before generating (project root differs from the default assumption).
## Related Skills
- `vercel:ai-sdk` — if your Inngest functions invoke LLMs, the AI SDK gives you streaming + provider abstraction; pair them with `step.run` for retry safety.
- `vercel:vercel-functions` — Inngest's `serve()` adapter for Next.js runs as a Vercel Serverless Function by default; the AI SDK skill has notes on Fluid Compute and timeout extension for long agent runs.
© pproenca · MIT · pproenca/dot-skills