OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add inngest/inngest-skills --skill inngest-setup
Use when adding durable execution to a TypeScript project — building retry-safe webhook handlers, background jobs that survive crashes, scheduled tasks, or long-running workflows that outlive a single request. Covers Inngest SDK installation, client config, environment variables, serve endpoints (Next.js, Express, Hono, Fastify), connect-as-worker mode, and the local dev server.
npx skills add inngest/inngest-skills --skill 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.
Install the inngest npm package in your project:
Create a shared client file that you'll import throughout your codebase:
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 EnvironmentsisDev: 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 v4signingKeyFallback: 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 contextmiddleware: Array of middleware (see inngest-middleware skill)Set these environment variables in your .env file or deployment environment:
⚠️ Common Gotcha: Never hardcode keys in your source code. Always use environment variables for INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY.
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):
Or in package.json scripts:
Symptoms of missing INNGEST_DEV:
/api/inngest returns {"code":"internal_server_error"}Inngest supports two connection modes:
Best for serverless platforms (Vercel, Lambda, etc.) and existing APIs.
Best for container runtimes (Kubernetes, Docker) and long-running processes.
Create an API endpoint that exposes your functions to Inngest:
🔧 Framework-Specific Notes:
express.json({ limit: "10mb" }) middleware to support larger function state.fastifyPlugin from inngest/fastifyinngest/cloudflareinngest/lambdaserve 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.
For long-running applications that maintain persistent connections:
Requirements for Connect Mode:
INNGEST_SIGNING_KEY and INNGEST_EVENT_KEY for productionappVersion parameter on the Inngest client for production to support rolling deploysv4 Connect Changes:
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)As your system grows, organize functions into logical apps:
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.
Start the Inngest Dev Server for local development:
The dev server will be available at http://localhost:8288 by default.
Create inngest.json for complex setups:
If your app runs on a non-standard port (not 3000), make sure the dev server can reach it by specifying the URL with -u flag.
Port Conflicts: If port 8288 is in use, specify a different port: -p 9999
Auto-discovery Not Working: Use manual URL specification: -u http://localhost:YOUR_PORT/api/inngest. If using --no-discovery flag, the -u flag is required — the dev server will not find your app without it.
Functions Not Showing in Dev Server: Your app must register with the dev server. This happens automatically when your serve endpoint receives its first request from the dev server. If registration isn't happening: (1) verify INNGEST_DEV=1 is set, (2) verify the dev server can reach your app URL, (3) try restarting your app while the dev server is running.
Signature Verification Errors: Ensure INNGEST_SIGNING_KEY is set correctly in production
WebSocket Connection Issues: Verify Node.js version 22.4+ for connect mode
Docker Development: Use host.docker.internal for app URLs when running dev server in Docker
inngest.createFunction()inngest.send() to trigger functionsThe dev server automatically reloads when you change functions, making development fast and iterative.
// 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).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"
})
);# 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:8288INNGEST_DEV=1{
"scripts": {
"dev": "INNGEST_DEV=1 tsx --watch src/server.ts"
}
}// 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]
})
);// 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");
})();// 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" });# Auto-discover your app on common ports/endpoints
npx --ignore-scripts=false inngest-cli@latest dev
# Specify your app's URL manually
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest
# Custom port for dev server
npx --ignore-scripts=false inngest-cli@latest dev -p 9999
# Disable auto-discovery
npx --ignore-scripts=false inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest
# Multiple apps
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest -u http://localhost:4000/api/inngest{
"sdk-url": [
"http://localhost:3000/api/inngest",
"http://localhost:4000/api/inngest"
],
"port": 8289,
"no-discovery": true
}INNGEST_DEV=1
# No keys required in dev modeINNGEST_EVENT_KEY=evt_your_production_event_key
INNGEST_SIGNING_KEY=signkey_your_production_signing_keyINNGEST_DEV=1
INNGEST_BASE_URL=http://localhost:9999