Inngest Setup

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+ recommended 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)
});
// IMPORTANT: v4 defaults to Cloud mode. For local dev, set INNGEST_DEV=1 env var.
// Without it, your serve endpoint will return 500 ("In cloud mode but no signing key").
// In production, set INNGEST_SIGNING_KEY (required for 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 INNGEST_DEV=1 env var for local development. Never hardcode isDev: true in source code — it will silently break in production. Always use the env var.
• 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: "user@example.com",
    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.

CRITICAL: Enable Dev Mode for Local Development

Before creating serve endpoints or connecting workers, ensure dev mode is enabled. Without it, Inngest defaults to Cloud mode and your endpoints will fail with 500 errors.

Add to your .env file (or your dev script in package.json):

INNGEST_DEV=1

Or in package.json scripts:

{
  "scripts": {
    "dev": "INNGEST_DEV=1 tsx --watch src/server.ts"
  }
}

Symptoms of missing INNGEST_DEV:

• GET /api/inngest returns {"code":"internal_server_error"}
• Server logs: "In cloud mode but no signing key found"
• Dev server can't sync with your app

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] }],
    instanceId: process.env.HOSTNAME, // Unique worker identifier
    maxWorkerConcurrency: 10, // Max concurrent steps
  });

  console.log("Worker connected:", connection.state);

  // Graceful shutdown handling
  await connection.closed;
  console.log("Worker shut down");
})();

Requirements for Connect Mode:

• Node.js 22.4+ (or Deno 1.4+, Bun 1.1+) for WebSocket support
• Long-running server environment (not serverless)
• INNGEST_SIGNING_KEY and INNGEST_EVENT_KEY for production
• Set the appVersion parameter on the Inngest client for production to support rolling deploys

v4 Connect Changes:

• Worker thread isolation is enabled by default — WebSocket connections execute in a worker thread to prevent event loop starvation. Set isolateExecution: false to use a single process (or INNGEST_CONNECT_ISOLATE_EXECUTION=false)
• rewriteGatewayEndpoint callback has been replaced with the gatewayUrl string option (or INNGEST_CONNECT_GATEWAY_URL env var)

Step 5: Organizing with Apps

As your system grows, organize functions into logical apps:

// User service
const userService = new Inngest({ id: "user-service" });

// Payment service
const paymentService = new Inngest({ id: "payment-service" });

// Email service
const emailService = new Inngest({ id: "email-service" });

Each app gets its own section in the Inngest dashboard and can be deployed independently. Use descriptive, hyphenated IDs that match your service architecture.

⚠️ Common Gotcha: Changing an app's id creates a new app in Inngest. Keep IDs consistent across deployments.