Inngest Setup

This skill sets up Inngest in a TypeScript project from scratch, covering installation, client configuration, connection modes, and local development.

These skills are focused on TypeScript. For Python or Go, refer to the Inngest documentation for language-specific guidance. Core concepts apply across all languages.

Prerequisites

• Node.js 18+ (Node.js 22.4+ r ecommended for WebSocket support)
• TypeScript project
• Package manager (npm, yarn, pnpm, or bun)

Step 1: Install the Inngest SDK

Install the inngest npm package in your project:

npm install inngest
# or
yarn add inngest
# or
pnpm add inngest
# or
bun add inngest

Step 2: Create an Inngest Client

Create a shared client file that you'll import throughout your codebase:

// src/inngest/client.ts
import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "my-app" // Unique identifier for your application (hyphenated slug)
});
// In development, you must set the INNGEST_DEV=1 env var or use isDev: true
// In production, INNGEST_SIGNING_KEY is required (v4 defaults to Cloud mode)

Key Configuration Options

• id (required): Unique identifier for your app. Use a hyphenated slug like "my-app" or "user-service"
• eventKey: Event key for sending events (prefer INNGEST_EVENT_KEY env var)
• env: Environment name for Branch Environments
• isDev: Force Dev mode (true) or Cloud mode (false). v4 defaults to Cloud mode, so set isDev: true or INNGEST_DEV=1 for local development
• signingKey: Signing key for production (prefer INNGEST_SIGNING_KEY env var). Moved from serve() to client in v4
• signingKeyFallback: Fallback signing key for key rotation (prefer INNGEST_SIGNING_KEY_FALLBACK env var)
• baseUrl: Custom Inngest API base URL (prefer INNGEST_BASE_URL env var)
• logger: Custom logger instance (e.g. winston, pino) — enables logger in function context
• middleware: Array of middleware (see inngest-middleware skill)

Typed Events with eventType()

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

const signupCompleted = eventType("user/signup.completed", {
  schema: z.object({
    userId: z.string(),
    email: z.string(),
    plan: z.enum(["free", "pro"])
  })
});

const orderPlaced = eventType("order/placed", {
  schema: z.object({
    orderId: z.string(),
    amount: z.number()
  })
});

export const inngest = new Inngest({ id: "my-app" });

// Use event types as triggers for full type safety:
inngest.createFunction(
  { id: "handle-signup", triggers: [signupCompleted] },
  async ({ event }) => {
    event.data.userId; /* typed as string */
  }
);

// Use event types when sending events:
await inngest.send(
  signupCompleted.create({
    userId: "user_123",
    email: "[email protected]",
    plan: "pro"
  })
);

Environment Variables Setup

Set these environment variables in your .env file or deployment environment:

# Required for production
INNGEST_EVENT_KEY=your-event-key-here
INNGEST_SIGNING_KEY=your-signing-key-here

# Force dev mode during local development
INNGEST_DEV=1

# Optional - custom dev server URL (default: http://localhost:8288)
INNGEST_BASE_URL=http://localhost:8288

⚠️ Common Gotcha: Never hardcode keys in your source code. Always use environment variables for INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY.

Step 3: Choose Your Connection Mode

Inngest supports two connection modes:

Mode A: Serve Endpoint (HTTP)

Best for serverless platforms (Vercel, Lambda, etc.) and existing APIs.

Mode B: Connect (WebSocket)

Best for container runtimes (Kubernetes, Docker) and long-running processes.

Step 4A: Serving an Endpoint (HTTP Mode)

Create an API endpoint that exposes your functions to Inngest:

// For Next.js App Router: src/app/api/inngest/route.ts
import { serve } from "inngest/next";
import { inngest } from "../../../inngest/client";
import { myFunction } from "../../../inngest/functions";

export const { GET, POST, PUT } = serve({
  client: inngest,
  functions: [myFunction]
});

// For Next.js Pages Router: pages/api/inngest.ts
import { serve } from "inngest/next";
import { inngest } from "../../inngest/client";
import { myFunction } from "../../inngest/functions";

export default serve({
  client: inngest,
  functions: [myFunction]
});

// For Express.js
import express from "express";
import { serve } from "inngest/express";
import { inngest } from "./inngest/client";
import { myFunction } from "./inngest/functions";

const app = express();
app.use(express.json({ limit: "10mb" })); // Required for Inngest, increase limit for larger function state

app.use(
  "/api/inngest",
  serve({
    client: inngest,
    functions: [myFunction]
  })
);

🔧 Framework-Specific Notes:

• Express: Must use express.json({ limit: "10mb" }) middleware to support larger function state.
• Fastify: Use fastifyPlugin from inngest/fastify
• Cloudflare Workers: Use inngest/cloudflare
• AWS Lambda: Use inngest/lambda
• For all other frameworks, check the serve reference here: https://www.inngest.com/docs-markdown/learn/serving-inngest-functions

⚠️ v4 Change: Options like signingKey, signingKeyFallback, and baseUrl are now configured on the Inngest client constructor, not on serve(). The serve() function only accepts client, functions, and streaming.

⚠️ Common Gotcha: Always use /api/inngest as your endpoint path. This enables automatic discovery. If you must use a different path, you'll need to configure discovery manually with the -u flag.

Step 4B: Connect as Worker (WebSocket Mode)

For long-running applications that maintain persistent connections:

// src/worker.ts
import { connect } from "inngest/connect";
import { inngest } from "./inngest/client";
import { myFunction } from "./inngest/functions";

(async () => {
  const connection = await connect({
    apps: [{ client: inngest, functions: [myFunction] }]