Inngest Nextjs Patterns

// =============================================================================
// Template: src/inngest/client.ts
// Parameters:
//   - appId (required): stable identifier for this Inngest app, kebab-case.
//                       Example: "acme-storefront". Never change after deploy —
//                       Inngest associates run history and replays with this ID.
//
// Generate ONCE per Next.js app. Subsequent functions and event-senders import
// from here. The client is a singleton — do not instantiate Inngest elsewhere.
//
// Env vars (read automatically by the SDK):
//   INNGEST_DEV=1          → connect to local dev server at http://localhost:8288
//   INNGEST_EVENT_KEY=...  → required in production for sending events
//   INNGEST_SIGNING_KEY=...→ required in production for the route handler to
//                            verify requests from Inngest Cloud
//
// See references/conventions.md § Function ID Stability for why appId is permanent.
// =============================================================================

import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "<APP_ID>", // e.g., "acme-storefront"
  // Optional: pass `isDev: true` to force dev mode regardless of env vars.
  // Leave this off in committed code — use INNGEST_DEV=1 locally instead.
});

// =============================================================================
// Template: src/inngest/events/<DOMAIN>.ts
// Parameters:
//   - DOMAIN (required): the event namespace, lowercase, no slash.
//                        Examples: "user", "order", "billing", "ai".
//   - EVENT_NAME (required): full event name in `<domain>/<entity>.<verb_past>`
//                            form. Examples: "user/account.created",
//                            "shop/order.placed", "billing/invoice.paid".
//   - SYMBOL (required): camelCase symbol exported for use as a trigger.
//                        Convention: matches the verb_past form, e.g.,
//                        accountCreated, orderPlaced, invoicePaid.
//   - PASCAL_SYMBOL (required): PascalCase form of SYMBOL, used in the sender
//                                helper name. E.g., SYMBOL=orderPlaced →
//                                PASCAL_SYMBOL=OrderPlaced → sendOrderPlaced.
//   - PAYLOAD shape: the `data` schema. Define with Zod for runtime validation
//                    at the system boundary (webhooks, public APIs); use
//                    staticSchema<T>() if the producer is fully internal and
//                    you trust TypeScript at compile time.
//
// One file per DOMAIN. Co-locating events keeps a domain's vocabulary in one
// place — when you change a payload, you change the schema and the producers
// in the same edit.
//
// See references/conventions.md § Event Naming and § One-Schema-Per-Event.
// =============================================================================

import { eventType } from "inngest";
import { z } from "zod";

import { inngest } from "@/inngest/client";

// -- Define the typed event ---------------------------------------------------
//
// `eventType` binds a string name to a payload schema. Functions that use this
// as a trigger get fully typed `event.data`. Senders use `.create()` to build a
// validated payload — TypeScript catches missing fields at the call site.

export const <SYMBOL> = eventType("<EVENT_NAME>", {
  schema: z.object({
    // Replace with your actual payload shape. Keep payloads small — pass IDs,
    // not whole objects. The function will reload fresh state inside step.run.
    id: z.string(),
    // userId: z.string(),
    // amountCents: z.number().int().nonnegative(),
  }),
});

// Optional: if runtime validation is overkill (purely internal producer),
// use staticSchema instead. Trade: no validation, but no Zod dependency.
//
//   import { staticSchema } from "inngest";
//   type <PASCAL_SYMBOL>Payload = { id: string };
//   export const <SYMBOL> = eventType("<EVENT_NAME>", {
//     schema: staticSchema<<PASCAL_SYMBOL>Payload>(),
//   });

// -- Typed sender helper ------------------------------------------------------
//
// Wrap inngest.send so callers don't have to remember the event name. Using
// `<SYMBOL>.create(...)` validates the payload at the call site.
//
// The function name is `send<PASCAL_SYMBOL>` — e.g., sendOrderPlaced. Substitute
// the PascalCase form into the identifier; the angle brackets disappear.

export async function send<PASCAL_SYMBOL>(data: z.infer<typeof <SYMBOL>.schema>) {
  await inngest.send(<SYMBOL>.create(data));
}

// =============================================================================
// Template: src/inngest/functions/<FN_FILE>.ts
// Parameters:
//   - FN_ID (required): stable kebab-case function ID. Never rename.
//   - FN_NAME (optional): friendly display name for the dashboard.
//   - CRON_EXPR (required): 5-field cron expression, optionally prefixed with
//                            "TZ=<IANA_zone> " for non-UTC schedules. Examples:
//                              "0 9 * * 1-5"  → 9am weekdays UTC
//                              "*/15 * * * *" → every 15 minutes UTC
//                              "TZ=America/New_York 0 9 * * 1-5"
//                                             → 9am ET weekdays (DST-aware)
//                            Default timezone is UTC. The TZ= prefix is part
//                            of the same string passed to cron().
//   - MANUAL_TRIGGER (optional): also accept an event for ad-hoc invocation.
//                                Useful for testing the cron logic from the dev UI.
//
// Cron-only functions receive NO event payload. The handler argument has step,
// logger, runId — but `event` is unused (it exists, but data is empty).
//
// AFTER GENERATING: add this function to src/inngest/functions/index.ts.
//
// See references/conventions.md § Cron vs Event Triggers.
// =============================================================================

import { cron } from "inngest";

import { inngest } from "@/inngest/client";
// If you also want a manual trigger, import an event symbol:
// import { <MANUAL_TRIGGER_SYMBOL> } from "@/inngest/events/<DOMAIN>";

export const <fnSymbol> = inngest.createFunction(
  {
    id: "<FN_ID>",
    name: "<FN_NAME>",

    // Cron-triggered functions run on schedule. Use the TZ= prefix for any
    // non-UTC schedule — DST-aware. Without TZ=, the expression evaluates in UTC.
    triggers: [
      cron("<CRON_EXPR>"), // e.g., cron("TZ=America/New_York 0 9 * * 1-5")
      // Optional: allow manual invocation by sending this event from anywhere.
      // Up to 10 triggers per function.
      // <MANUAL_TRIGGER_SYMBOL>,
    ],

    // Flow control for crons is usually about preventing overlap when a run
    // takes longer than the schedule interval. concurrency: { limit: 1 } makes
    // the cron strictly serial — a slow run delays the next tick instead of
    // stacking up parallel runs.
    concurrency: { limit: 1, scope: "fn" },

    // Crons usually shouldn't retry forever — a missed tick is often better
    // than a stuck queue. Tune based on idempotency of the work.
    retries: 2,
  },
  async ({ step, logger }) => {
    logger.info({ at: new Date().toISOString() }, "<FN_ID> tick");

    // Typical cron pattern: enumerate work, then fan out via events instead of
    // doing all of it inline. Keeps each individual job independently retryable.
    const items = await step.run("collect-work", async () => {
      // Query the DB / API for items to process this tick.
      // Return an array of identifiers — keep step results small.
      return [] as Array<{ id: string }>;
    });

    // Option A: fan out one event per item (preferred when work is per-item).
    // The other functions handle retries and concurrency for their own work.
    if (items.length > 0) {
      await step.sendEvent(
        "fan-out",
        items.map((item) => ({
          name: "<domain/entity.verb_past>", // the per-item event
          data: { id: item.id },
        })),
      );
    }

    // Option B: do the work inline if it's a small, atomic batch.
    // for (const item of items) {
    //   await step.run(`process-${item.id}`, async () => doWork(item));
    // }

    return { processed: items.length };
  },
);

// =============================================================================
// Template: src/inngest/functions/<FN_FILE>.ts
// Parameters:
//   - FN_ID (required): stable kebab-case ID. Example: "import-contacts".
//   - PARENT_EVENT (required): the trigger event symbol. The orchestrator's job.
//   - CHILD_EVENT (required): the per-item event symbol that worker functions consume.
//   - MODE (required): one of:
//       "fire-and-forget" → step.sendEvent for each item, return immediately.
//                            Use when the orchestrator doesn't need results.
//       "wait-for-results" → Promise.all(step.invoke(...)) per item.
//                             Orchestrator returns once all children finish.
//
// Fan-out has two distinct shapes — pick deliberately. Fire-and-forget scales
// to millions of items (events are cheap). wait-for-results is bounded by the
// concurrency of the child function and the orchestrator's runtime.
//
// Why fan out at all? Each child becomes its own durable run — it retries,
// reports, and observes independently in the dashboard. One bad item can't
// stall the others.
//
// See references/conventions.md § Fan-Out Patterns.
// =============================================================================

import { <PARENT_EVENT> } from "@/inngest/events/<DOMAIN>";
// For "wait-for-results" mode, also import the child function:
// import { <childFnSymbol> } from "@/inngest/functions/<child-fn-file>";

import { inngest } from "@/inngest/client";

export const <fnSymbol> = inngest.createFunction(
  {
    id: "<FN_ID>",
    name: "<FN_NAME>",

    // Orchestrators usually need higher concurrency than their children — the
    // bottleneck is the child function's limit, not this one.
    concurrency: { limit: 50, scope: "fn" },
    retries: 3,

    // v4 trigger array — pass the imported event symbol directly.
    triggers: [<PARENT_EVENT>],
  },
  async ({ event, step, logger }) => {
    // 1. Resolve the work set INSIDE a step so the list is durable. Re-running
    //    the orchestrator must produce the same fan-out, or replays will
    //    double-dispatch.
    const items = await step.run("resolve-work-set", async () => {
      // Return an array of stable identifiers, not whole objects.
      return [{ id: "1" }, { id: "2" }] as Array<{ id: string }>;
    });

    logger.info({ count: items.length }, "<FN_ID> fan-out");

    // -------------------------------------------------------------------------
    // MODE: fire-and-forget
    // -------------------------------------------------------------------------
    // Send one event per item. Each child run is independent. Return now.

    await step.sendEvent(
      "dispatch",
      items.map((item) => ({
        name: "<child/event.name>", // e.g., "import/contact.requested"
        data: { id: item.id, parentRunId: event.id },
      })),
    );

    return { dispatched: items.length };

    // -------------------------------------------------------------------------
    // MODE: wait-for-results
    // -------------------------------------------------------------------------
    // Swap the return above for the block below. Each step.invoke runs the
    // child function inline (within the same logical workflow) and returns
    // its result. Promise.all parallelizes the calls.
    //
    // Bound the batch size — Promise.all over 10,000 invokes will exhaust
    // memory. Chunk if items.length > a few hundred.
    //
    // const results = await Promise.all(
    //   items.map((item, idx) =>
    //     step.invoke(`child-${item.id}-${idx}`, {
    //       function: <childFnSymbol>,
    //       data: { id: item.id },
    //       timeout: "10m",
    //     }),
    //   ),
    // );
    // return { processed: results.length, results };
  },
);

// =============================================================================
// Template: src/inngest/functions/<FN_FILE>.ts
// Parameters:
//   - FN_ID (required): stable kebab-case function ID. Never rename.
//                       Example: "process-order", "send-welcome-email".
//   - FN_NAME (optional): friendly display name for the Inngest dashboard.
//   - TRIGGER_SYMBOL (required): imported event symbol from
//                                 src/inngest/events/<domain>.ts
//   - retries (optional, default 4): integer 0–20. 0 disables retries.
//   - concurrency (optional): number (limit) OR full object
//                              { limit, key, scope: "fn" | "env" | "account" }
//   - throttle / rateLimit / debounce (optional): see flow-control blocks below
//   - cancelOn (optional): array of { event, match } for cancellation
//   - onFailure (optional, boolean): include the after-retries-exhausted hook
//
// AFTER GENERATING: add this function to src/inngest/functions/index.ts so the
// route handler picks it up. The registry pattern is in references/conventions.md.
//
// See references/conventions.md § Step Idempotency before filling in step bodies.
// =============================================================================

import { <TRIGGER_SYMBOL> } from "@/inngest/events/<DOMAIN>";
import { inngest } from "@/inngest/client";

export const <fnSymbol> = inngest.createFunction(
  {
    id: "<FN_ID>",
    name: "<FN_NAME>", // optional — delete if same as id

    // -- Flow control (all optional) ------------------------------------------
    // Pick the controls your function actually needs. Don't add them "just in
    // case" — every control has a runtime cost and a debugging cost.

    retries: 4, // default 4. Set 0 only if the work is genuinely fire-and-forget.

    concurrency: {
      // Cap simultaneous runs. Scope "fn" = across all events for THIS function.
      // Scope "env" / "account" share the limit across functions.
      limit: 10,
      scope: "fn",
      // Optional: per-key isolation. Different tenants get separate concurrency
      // buckets so one heavy tenant can't starve others.
      // key: "event.data.accountId",
    },

    // throttle: { limit: 5, period: "1m", key: "event.data.userId" },
    // rateLimit: { limit: 100, period: "1h", key: "event.data.accountId" },
    // debounce: { period: "5s", key: "event.data.userId", timeout: "30s" },

    // -- Trigger --------------------------------------------------------------
    // v4 places triggers inside the config object as an array. Pass the imported
    // event symbol directly — it carries the event name AND payload schema, so
    // `event.data` below is fully typed.
    triggers: [<TRIGGER_SYMBOL>],

    // -- Cancellation ---------------------------------------------------------
    // Cancel an in-flight run when a matching event arrives. `match` is a JSON
    // path on event.data — both events must share that field's value.

    // cancelOn: [
    //   { event: "<domain/entity.verb_past>", match: "data.id" },
    // ],

    // timeouts: { finish: "30m" }, // cancel run if it exceeds 30 minutes total

    // -- After-all-retries-exhausted handler ----------------------------------
    // Runs once after the final retry fails. Use for alerting, NOT for retry
    // logic — Inngest already did that.

    // onFailure: async ({ error, event }) => {
    //   await alertOpsChannel({
    //     functionId: "<FN_ID>",
    //     error: error.message,
    //     payload: event.data,
    //   });
    // },
  },
  async ({ event, step, logger, attempt }) => {
    logger.info({ attempt, id: event.data.id }, "<FN_ID> start");

    // -------------------------------------------------------------------------
    // Steps. EVERY external side effect MUST be wrapped in step.run.
    //
    // The function body re-executes from the top on each step boundary, but
    // step.run results are memoized: on replay, Inngest returns the cached
    // result instead of running the closure again. That means:
    //
    //   1. Code OUTSIDE step.run runs multiple times — keep it pure.
    //   2. Code INSIDE step.run runs once on success, multiple times on retry.
    //      It must be idempotent (use idempotency keys, upserts, or check-then-act).
    //   3. Step IDs are durable — renaming "charge" → "charge-customer" re-runs
    //      that step from scratch on replay.
    // -------------------------------------------------------------------------

    const result = await step.run("<step-id-kebab-case>", async () => {
      // Idempotent external side effect goes here.
      // Example: stripe.charges.create({ ..., idempotency_key: event.data.id })
      return { ok: true, id: event.data.id };
    });

    // Durable sleep — function actually unloads from memory and resumes later.
    // Use this for SLA-style delays ("wait 1h then check"), reminders, etc.
    // await step.sleep("wait", "1h");
    // await step.sleepUntil("wait-until-renewal", event.data.renewsAt);

    // Pause until another event arrives. Returns the matched event or null on
    // timeout. Match links events by a shared field (here: data.id).
    // const followUp = await step.waitForEvent("await-confirmation", {
    //   event: "<other/event.name>",
    //   timeout: "7d",
    //   match: "data.id",
    // });
    // if (!followUp) {
    //   // timeout branch
    // }

    return { ok: true, result };
  },
);

// =============================================================================
// Template: src/app/api/inngest/route.ts
// Parameters: (none — reads from the function registry)
//
// The single endpoint Inngest Cloud (and the local dev server) calls to invoke
// your functions. It exports GET, POST, and PUT — all three are required:
//
//   GET  → introspection: Inngest fetches the list of registered functions
//   POST → invocation: Inngest calls this when an event triggers a function
//   PUT  → register: Inngest pings this to register new functions on deploy
//
// This file should rarely change. Adding a new function = adding it to
// src/inngest/functions/index.ts (the registry), NOT to this file.
//
// See references/conventions.md § Function Registry.
// =============================================================================

import { serve } from "inngest/next";

import { inngest } from "@/inngest/client";
import { functions } from "@/inngest/functions";

export const { GET, POST, PUT } = serve({
  client: inngest,
  functions,
  // Optional: streaming (only on platforms that support it — Vercel doesn't):
  //   streaming: "allow",
  // Optional: override the served path if you mount this at a non-default URL:
  //   servePath: "/api/inngest",
});

{
  "client_path": "src/inngest/client.ts",
  "route_path": "src/app/api/inngest/route.ts",
  "events_dir": "src/inngest/events",
  "functions_dir": "src/inngest/functions",
  "schema_library": "zod",
  "app_id": "",
  "_setup_instructions": {
    "client_path": "Where to write the Inngest client singleton. Default assumes Next.js src/ + App Router. Change if your project uses app/ without src/, or Pages Router.",
    "route_path": "Where to write the Inngest serve() handler. For App Router, ends in route.ts. For Pages Router, use pages/api/inngest.ts and the templates need light adjustment (default export instead of named GET/POST/PUT exports).",
    "events_dir": "Directory for typed event definitions. One file per domain (e.g., events/shop.ts, events/user.ts).",
    "functions_dir": "Directory for function definitions plus the registry index.ts.",
    "schema_library": "Either 'zod' (runtime validation at boundaries) or 'static' (compile-time only, no Zod dependency). The event template branches on this.",
    "app_id": "Stable kebab-case ID for this Inngest app, written into client.ts. NEVER change after deploy — Inngest associates run history with this ID. Example: 'acme-storefront'."
  }
}

{
  "version": "1.0.3",
  "organization": "personal",
  "technology": "Inngest + Next.js",
  "discipline": "extraction",
  "type": "scaffolding",
  "date": "May 2026",
  "abstract": "Parameterized templates for building event-driven, durable background work on Inngest from a Next.js App Router project. Covers the one-time setup (client singleton, /api/inngest route handler), recurring scaffolds (typed events with Zod schemas, event-driven and cron-triggered durable functions, fan-out orchestrators), and the conventions that make Inngest's retry/replay/concurrency model actually work (event naming, function-id stability, step idempotency).",
  "references": [
    "https://www.inngest.com/docs/getting-started/nextjs-quick-start",
    "https://www.inngest.com/docs/reference/typescript/v4/functions/triggers",
    "https://www.inngest.com/docs/reference/typescript/v4/migrations/v3-to-v4",
    "https://www.inngest.com/docs/guides/step-parallelism",
    "https://www.inngest.com/docs/guides/throttling",
    "https://www.inngest.com/docs/guides/flow-control"
  ]
}