Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill inngest-nextjs-patterns -a claude-code
Open on GitHub

What 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.placed event 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-code

2Manually: put the files in place

~/.claude/skills/inngest-nextjs-patterns/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/inngest-nextjs-patterns/

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

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
implementation-design-patterns-python implementation-design-patterns-python — a Python design-pattern guide for choosing an approach when conditionals, inheritance, or object relationships start to sprawl. It favors modern Python idioms over class-heavy templates. CX Codex +1 143installs better-auth-scaffold better-auth-scaffold scaffolds Better Auth in a Next.js App Router project on Drizzle: file templates, three plugin presets, schema generation and migrations. CX Codex +1 143installs expo-ui Guidance for building and reviewing React Native screens with @expo/ui on iOS. Useful when adopting SwiftUI views or working with iOS 26 interface features. CX Codex +1 142installs design-to-react-algorithms The design-to-react-algorithms skill provides a step-by-step pipeline to convert Sketch files into React and CSS while preventing layout regressions. CX Codex +1 142installs acceptance-pipeline-catalog acceptance-pipeline-catalog guides code agents through building, reviewing, and debugging Gherkin acceptance test pipelines with mutation testing based on Robert C. Martin's specification. CX Codex +1 142installs nuqs-codemod-runner nuqs-codemod-runner finds pre-v2.5 nuqs patterns, produces a dry-run migration preview, and applies safe jscodeshift transforms gated by type checking and linting. CX Codex +1 142installs acceptance-pipeline-feature-design The acceptance-pipeline-feature-design skill helps design Acceptance Pipeline extensions, covering Gherkin syntax, JSON IR fields, pipeline stages, mutation strategies, and reports. CX Codex +1 141installs dx-harness dx-harness — a skill for Claude Code, Cursor, and other IDEs that finds and fixes developer-loop friction — slow onboarding, repeated manual steps, missing bootstrap and reset scripts. CX Codex +1 141installs

Project sponsors

Companies that keep this analytics open