Package Exports

nestjs-inngest
nestjs-inngest/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (nestjs-inngest) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

NestJS Inngest Integration

🚀 Simple, unified NestJS integration for Inngest with multi-platform support and type safety.

✨ Features

Core Features

🚀 Seamless NestJS Integration - Native dependency injection and NestJS patterns
⚡ Multi-Platform Support - Works with both Express and Fastify HTTP platforms
🔒 Type Safety - Full TypeScript support with typed event definitions and handlers
🎯 Decorator-Based - Simple @InngestFunction decorator for defining serverless functions
🔄 Automatic Discovery - Zero-config function registration and discovery
🎛️ Unified API - Single createServe() method works with both platforms
🎮 Controller Integration - Custom NestJS controller support with createControllerHandler()

Developer Experience

🔧 Simplified Configuration - Streamlined module setup with essential options only
📝 Error Handling - Comprehensive error reporting with detailed validation messages
🐛 Debug Logging - Enhanced logging for development and troubleshooting
🧪 Basic Testing - Simple testing utilities for unit and integration tests
🎯 Flexible Integration - Choose between automatic middleware/plugin or custom controller integration

Quick Start

1. Module Setup

First, configure the InngestModule in your NestJS application:

import { Module } from "@nestjs/common";
import { InngestModule } from "nestjs-inngest";

@Module({
  imports: [
    InngestModule.forRoot({
      appId: "my-nestjs-app",
      // signingKey and eventKey not required in local, but required in Inngest-Cloud or your self-host, you need add NODE_ENV === "development" into .env file
      signingKey: process.env.INNGEST_SIGNING_KEY, // Inngest authenticates to me when calling my functions
      eventKey: process.env.INNGEST_EVENT_KEY, // I authenticate to Inngest when sending events
    }),
  ],
})
export class AppModule {}

2. HTTP Platform Setup

This module supports both Express and Fastify HTTP platforms with a unified API. You can choose between automatic integration (middleware/plugin) or controller-based integration for more control.

Option A: Automatic Integration (Recommended)

import { NestFactory } from "@nestjs/core";
import { NestExpressApplication } from "@nestjs/platform-express";
import {
  NestFastifyApplication,
  FastifyAdapter,
} from "@nestjs/platform-fastify";
import { InngestService } from "nestjs-inngest";
import { AppModule } from "./app.module";

async function bootstrap() {
  // Platform switch - change this to switch platforms
  const USE_FASTIFY = false; // Set to true for Fastify, false for Express

  if (USE_FASTIFY) {
    // Create Fastify application
    const app = await NestFactory.create<NestFastifyApplication>(
      AppModule,
      new FastifyAdapter()
    );

    // Setup Inngest Fastify plugin
    const inngestService = app.get(InngestService);
    const { plugin, options } = await inngestService.createServe("fastify");
    await app.register(plugin, options);

    await app.listen(3000, "0.0.0.0");
  } else {
    // Create Express application
    const app = await NestFactory.create<NestExpressApplication>(AppModule, {
      bodyParser: false,
    });

    // Configure Express body parser
    app.useBodyParser("json", { limit: "10mb" });

    // Setup Inngest Express middleware
    const inngestService = app.get(InngestService);
    const serveMiddleware = await inngestService.createServe("express");
    app.use("/api/inngest", serveMiddleware);

    await app.listen(3000);
  }
}
bootstrap();

Option B: Controller-Based Integration

For more control over the Inngest webhook endpoint, you can use a custom NestJS controller:

Express Controller Example:

// express-inngest.controller.ts
import { Controller, Post, Put, Get, Req, Res, Logger } from "@nestjs/common";
import { InngestService } from "nestjs-inngest";

@Controller("api/inngest")
export class ExpressInngestController {
  private readonly logger = new Logger(ExpressInngestController.name);

  constructor(private readonly inngestService: InngestService) {}

  @Get()
  async handleIntrospection(
    @Req() req: any,
    @Res({ passthrough: false }) res: any
  ) {
    return this.handleInngestRequest(req, res, "GET");
  }

  @Post()
  async handleWebhook(@Req() req: any, @Res({ passthrough: false }) res: any) {
    return this.handleInngestRequest(req, res, "POST");
  }

  @Put()
  async handlePutWebhook(
    @Req() req: any,
    @Res({ passthrough: false }) res: any
  ) {
    return this.handleInngestRequest(req, res, "PUT");
  }

  private async handleInngestRequest(req: any, res: any, method: string) {
    try {
      // Use the controller-specific handler for Express
      const controllerHandler =
        await this.inngestService.createControllerHandler("express");
      return controllerHandler(req, res);
    } catch (error) {
      this.logger.error("Error in Inngest controller:", error);
      return res.status(500).json({ error: "Internal Server Error" });
    }
  }
}

Fastify Controller Example:

// fastify-inngest.controller.ts
import { Controller, Post, Put, Get, Req, Res, Logger } from "@nestjs/common";
import { InngestService } from "nestjs-inngest";
import type { FastifyRequest, FastifyReply } from "fastify";

@Controller("api/inngest")
export class FastifyInngestController {
  private readonly logger = new Logger(FastifyInngestController.name);

  constructor(private readonly inngestService: InngestService) {}

  @Get()
  async handleIntrospection(
    @Req() req: FastifyRequest,
    @Res({ passthrough: false }) res: FastifyReply
  ) {
    return this.handleInngestRequest(req, res, "GET");
  }

  @Post()
  async handleWebhook(
    @Req() req: FastifyRequest,
    @Res({ passthrough: false }) res: FastifyReply
  ) {
    return this.handleInngestRequest(req, res, "POST");
  }

  @Put()
  async handlePutWebhook(
    @Req() req: FastifyRequest,
    @Res({ passthrough: false }) res: FastifyReply
  ) {
    return this.handleInngestRequest(req, res, "PUT");
  }

  private async handleInngestRequest(
    req: FastifyRequest,
    res: FastifyReply,
    method: string
  ) {
    try {
      // Use the controller-specific handler for Fastify
      const controllerHandler =
        await this.inngestService.createControllerHandler("fastify");
      return await controllerHandler(req, res);
    } catch (error) {
      this.logger.error("Error in Fastify Inngest controller:", error);
      return res.status(500).send({
        error: "Internal Server Error",
        message: error.message,
      });
    }
  }
}

Main Application (Fastify with Controller):

// main.ts
import { NestFactory } from "@nestjs/core";
import { FastifyAdapter } from "@nestjs/platform-fastify";
import type { NestFastifyApplication } from "@nestjs/platform-fastify";
import { AppModule } from "./app.module";

async function bootstrap() {
  // Create Fastify application
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter()
  );

  await app.listen(3000, "0.0.0.0");
  console.log(
    "🚀 Fastify app with Inngest controller running on http://localhost:3000"
  );
  console.log("🎯 Inngest webhook: http://localhost:3000/api/inngest");
}
bootstrap();

Don't forget to add the controller to your module:

// app.module.ts
import { Module } from "@nestjs/common";
import { InngestModule } from "nestjs-inngest";
import { FastifyInngestController } from "./fastify-inngest.controller";

@Module({
  imports: [
    InngestModule.forRoot({
      appId: "my-fastify-app",
      signingKey: process.env.INNGEST_SIGNING_KEY,
      eventKey: process.env.INNGEST_EVENT_KEY,
    }),
  ],
  controllers: [FastifyInngestController],
})
export class AppModule {}

Integration Method Comparison

Feature	Automatic Integration	Controller Integration
Setup Complexity	✅ Simple	🟡 Medium
Control Level	🟡 Standard	✅ Full Control
Custom Logic	❌ Limited	✅ Full Support
Error Handling	🟡 Basic	✅ Custom
Middleware Support	✅ Built-in	✅ NestJS Decorators
Best For	Quick setup, standard use cases	Custom logic, advanced error handling

Note: Both createServe() and createControllerHandler() methods provide a unified API that works with both Express and Fastify platforms!

3. Define Event Types (Optional but Recommended)

Create type-safe event definitions:

import { EventTypes } from "nestjs-inngest";

export type MyEventTypes = EventTypes<{
  "user.created": { userId: string; email: string; name: string };
  "order.placed": { orderId: string; userId: string; total: number };
  "email.send": { to: string; template: string; data: any };
}>;

4. Create Inngest Functions

Use the @InngestFunction decorator to define serverless functions:

import { Injectable } from "@nestjs/common";
import { InngestFunction, InngestFunctionContext } from "nestjs-inngest";

@Injectable()
export class UserService {
  @InngestFunction({
    id: "user-welcome-flow",
    name: "User Welcome Flow",
    triggers: [{ event: "user.created" }],
  })
  async handleUserCreated(
    event: any,
    { step, logger, runId, attempt }: InngestFunctionContext
  ) {
    const { userId, email, name } = event.data;

    // Step 1: Create user profile
    const profile = await step.run("create-profile", async () => {
      return this.createUserProfile(userId, { email, name });
    });

    // Step 2: Send welcome email
    await step.run("send-welcome-email", async () => {
      return this.sendEmail({
        to: email,
        template: "welcome",
        data: { name, userId },
      });
    });

    // Step 3: Send event notification
    await step.sendEvent("send-notification", {
      name: "user.notification",
      data: { userId, type: "welcome", email },
    });

    return { success: true, userId, profileId: profile.id };
  }

  private async createUserProfile(userId: string, data: any) {
    // Your implementation
  }

  private async sendEmail(params: any) {
    // Your implementation
  }
}

5. Send Events

Inject the InngestService to send events:

import { Injectable } from "@nestjs/common";
import { InngestService } from "nestjs-inngest";

@Injectable()
export class AuthService {
  constructor(private readonly inngestService: InngestService) {}

  async createUser(userData: any) {
    // Create user in database
    const user = await this.userRepository.save(userData);

    // Trigger Inngest function
    await this.inngestService.send({
      name: "user.created",
      data: {
        userId: user.id,
        email: user.email,
        name: user.name,
      },
    });

    return user;
  }
}

Installation

npm install nestjs-inngest inngest
# or
yarn add nestjs-inngest inngest
# or
pnpm add nestjs-inngest inngest

Configuration

Basic Configuration

InngestModule.forRoot({
  appId: "my-app", // Required: Your app identifier
  signingKey: "your-key", // Required: For webhook verification
  eventKey: "your-event-key", // Required: For sending events
  endpoint: "/api/inngest", // Optional: Webhook endpoint path
  env: "production", // Optional: Environment
  timeout: 30000, // Optional: Function timeout in ms
});

Async Configuration

InngestModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: async (configService: ConfigService) => ({
    appId: configService.get("INNGEST_APP_ID"),
    signingKey: configService.get("INNGEST_SIGNING_KEY"),
    eventKey: configService.get("INNGEST_EVENT_KEY"),
    env: configService.get("NODE_ENV"),
  }),
  inject: [ConfigService],
});

Configuration Options

Complete Parameter Reference

// Synchronous configuration
InngestModule.forRoot({
  // === REQUIRED PARAMETERS ===
  appId: "my-app", // 🔵 Inngest: Your app identifier

  // === INNGEST CORE PARAMETERS ===
  signingKey: process.env.INNGEST_SIGNING_KEY, // 🔵 Inngest: Webhook signature verification
  eventKey: process.env.INNGEST_EVENT_KEY, // 🔵 Inngest: Event sending authentication
  baseUrl: "https://api.inngest.com", // 🔵 Inngest: API base URL (defaults to Inngest cloud)
  isDev: process.env.NODE_ENV === "development", // 🔵 Inngest: Development mode flag

  // === CONNECTION METHODS ===
  enableConnect: false, // 🟠 Extension: Use connect mode vs serve mode (default: false)

  // === HTTP & ROUTING ===
  endpoint: "/api/inngest", // 🟠 Extension: Webhook endpoint path (default: "/api/inngest")

  // === PERFORMANCE & LIMITS ===
  timeout: 30000, // 🔵 Inngest: Function timeout in ms (default: 30000)
  maxBatchSize: 100, // 🟠 Extension: Max events per batch (default: 100)

  // === DEVELOPMENT & DEBUGGING ===
  logger: true, // 🟠 Extension: Enable detailed logging (default: true)
  env: "development", // 🟠 Extension: Environment setting ("production"|"development"|"test")
  strict: false, // 🟠 Extension: Enhanced validation (default: false)

  // === RETRY CONFIGURATION ===
  retry: {
    maxAttempts: 3, // 🟠 Extension: Maximum retry attempts (default: 3)
    initialDelay: 1000, // 🟠 Extension: Initial delay between retries in ms (default: 1000)
    maxDelay: 30000, // 🟠 Extension: Maximum delay between retries in ms (default: 30000)
    backoff: "exponential", // 🟠 Extension: Backoff strategy ("exponential"|"linear"|"fixed")
    backoffMultiplier: 2, // 🟠 Extension: Backoff multiplier (default: 2)
  },

  // === DEVELOPMENT MODE (Advanced) ===
  development: {
    enabled: true, // 🟠 Extension: Enable development features
    mockExternalCalls: false, // 🟠 Extension: Mock external service calls
    localWebhookUrl: "http://localhost:3000", // 🟠 Extension: Custom local webhook URL
    disableSignatureVerification: true, // 🟠 Extension: Skip signature validation
    enableIntrospection: true, // 🟠 Extension: Function debugging tools
    autoRegisterFunctions: true, // 🟠 Extension: Auto-discover functions
    developmentTimeout: 60000, // 🟠 Extension: Extended timeout for debugging
    enableStepDebugging: true, // 🟠 Extension: Step-by-step execution logs
  },
});
// Inngest SDK
if (process.env.NODE_ENV === "development" || process.env.INNGEST_DEV === "1") {
  // auto disabled
  signatureVerification = false;
}

// Asynchronous configuration with environment variables
InngestModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: async (configService: ConfigService) => ({
    appId: configService.get("INNGEST_APP_ID"),
    signingKey: configService.get("INNGEST_SIGNING_KEY"),
    eventKey: configService.get("INNGEST_EVENT_KEY"),
    isDev: configService.get("NODE_ENV") === "development",
    enableConnect: configService.get("INNGEST_USE_CONNECT") === "true",
    // ... other parameters
  }),
  inject: [ConfigService],
});

Parameter Categories

🔵 Inngest Core Parameters - Native Inngest SDK parameters:

appId, signingKey, eventKey, baseUrl, isDev, timeout

🟠 NestJS Extension Parameters - Our enhancements for better NestJS integration:

Connection management: enableConnect, endpoint
Development tools: logger, env, strict, development.*
Performance: maxBatchSize, retry.*

Quick Examples

Minimal Setup:

InngestModule.forRoot({
  appId: "my-app",
  // signingKey and eventKey not required in local, but required in Inngest-Cloud or your self-host, you need add NODE_ENV === "development" into .env file
  signingKey: process.env.INNGEST_SIGNING_KEY, // Inngest authenticates to me when calling my functions
  eventKey: process.env.INNGEST_EVENT_KEY, // I authenticate to Inngest when sending events
});

Development Setup:

InngestModule.forRoot({
  appId: "my-dev-app",
  isDev: true,
  development: {
    enabled: true,
    disableSignatureVerification: true,
  },
});

Production Setup:

InngestModule.forRoot({
  appId: "my-prod-app",
  signingKey: process.env.INNGEST_SIGNING_KEY,
  eventKey: process.env.INNGEST_EVENT_KEY,
  env: "production",
  logger: false,
  strict: true,
  retry: { maxAttempts: 5 },
});

Step Functions

Inngest provides step functions for reliable, resumable workflows:

@InngestFunction({
  id: 'user-workflow',
  triggers: [{ event: 'user.created' }],
})
async handleUserWorkflow(event: any, { step }: any) {
  // Steps are automatically retried on failure
  const profile = await step.run('create-profile', async () => {
    return this.createUserProfile(event.data);
  });

  // Sleep/delay execution
  await step.sleep('wait-before-email', '1 minute');

  // Send events to trigger other functions
  await step.sendEvent('send-welcome-email', {
    name: 'email.send',
    data: { userId: profile.id, email: event.data.email }
  });

  return { success: true, profileId: profile.id };
}

Type Safety (Optional)

For applications requiring strict type safety, use the typed decorator with your event schema:

import { TypedInngestFunction, EventRegistry } from "nestjs-inngest";

// Define your event types
interface MyEventRegistry extends EventRegistry {
  "user.created": { userId: string; email: string; name: string };
  "order.completed": { orderId: string; amount: number; userId: string };
  "email.sent": { to: string; subject: string; success: boolean };
}

@Injectable()
export class UserService {
  @TypedInngestFunction<MyEventRegistry, "user.created">({
    id: "user-welcome-flow",
    triggers: [{ event: "user.created" }],
    config: {
      retries: 3,
      timeout: 30000,
      priority: 1,
    },
  })
  async handleUserCreated({
    event,
    step,
  }: TypedEventContext<MyEventRegistry, "user.created">) {
    // event.data is strictly typed as { userId: string; email: string; name: string }
    const { userId, email, name } = event.data;

    return await step.run("create-profile", async () => {
      return this.createUserProfile({ userId, email, name });
    });
  }
}

Advanced Type Helpers

Create event-specific decorators:

import { createEventDecorator, CronFunction } from "nestjs-inngest";

// Create a user-created specific decorator
const UserCreatedFunction = createEventDecorator<MyEventRegistry, 'user.created'>('user.created');

// Use the specific decorator
@UserCreatedFunction({
  id: "send-welcome-email",
  name: "Send Welcome Email"
})
async sendWelcomeEmail({ event }: TypedEventContext<MyEventRegistry, 'user.created'>) {
  // Automatically typed for user.created events
}

// Cron-based functions
@CronFunction({
  id: "daily-cleanup",
  cron: "0 2 * * *", // 2 AM daily
  timezone: "UTC"
})
async dailyCleanup() {
  // Scheduled function
}

Performance Optimization (Optional)

For applications with many functions or high-performance requirements, you can use the optimized decorator:

import { OptimizedInngestFunction } from "nestjs-inngest";

@Injectable()
export class UserService {
  @OptimizedInngestFunction({
    id: "user-welcome-flow",
    triggers: [{ event: "user.created" }],
  })
  async handleUserCreated(event: any, { step }: any) {
    // Same functionality as @InngestFunction, but with:
    // - Multi-layer caching for faster metadata processing
    // - Memory optimization with object pooling
    // - Batch validation and lookup capabilities
    // - Performance monitoring and statistics

    return await step.run("process-user", async () => {
      return this.processUser(event.data);
    });
  }
}

Performance Monitoring

Monitor decorator performance in high-load scenarios:

import {
  getDecoratorPerformanceStats,
  clearOptimizedCaches,
} from "nestjs-inngest";

// Get performance statistics
const stats = getDecoratorPerformanceStats();
console.log({
  registeredClasses: stats.registeredClasses,
  totalFunctions: stats.totalFunctions,
  cacheHitRate: stats.cacheHitRate,
  memoryUsage: stats.memoryUsage,
});

// Clear caches when needed (e.g., during testing)
clearOptimizedCaches();

Decorator Comparison

Feature	`@InngestFunction`	`@TypedInngestFunction`	`@OptimizedInngestFunction`	`@CronFunction`
Type Safety	❌ Basic (`any`)	✅ Strict TypeScript	❌ Basic (`any`)	✅ Typed Config
Performance	🟢 Standard	🟢 Standard	✅ Optimized	🟢 Standard
Event Validation	🟡 Runtime only	✅ Compile + Runtime	🟡 Runtime only	✅ Compile Time
Memory Usage	🟢 Low	🟢 Low	🟡 Higher (caching)	🟢 Low
Complexity	🟢 Simple	🟡 Medium	🟡 Medium	🟢 Simple
IDE Support	🟡 Basic	✅ Full IntelliSense	🟡 Basic	✅ Full IntelliSense
Trigger Types	✅ Event + Cron	✅ Event + Cron	✅ Event + Cron	🎯 Cron Only
Best For	General use	Type-safe apps	High-performance apps	Scheduled tasks

When to Use Each Decorator

@InngestFunction (Recommended for most cases)

✅ General purpose applications
✅ Quick prototyping and development
✅ Simple event handling
✅ When type safety is not critical

@TypedInngestFunction (For type-safe applications)

✅ Large applications with complex event schemas
✅ Teams requiring strict type safety
✅ When you want compile-time event validation
✅ Better IDE support and IntelliSense

@OptimizedInngestFunction (For high-performance scenarios)

✅ Applications with 50+ Inngest functions
✅ High-frequency function registration/discovery
✅ Performance-critical environments
✅ When you need performance monitoring

@CronFunction (For scheduled tasks)

✅ Pure cron-based scheduled tasks
✅ When you want clean, explicit cron syntax
✅ Type-safe cron configuration with timezone support
✅ Priority and timeout configuration for scheduled jobs
✅ Cleaner than manually configuring cron triggers

CronFunction Examples

import { CronFunction } from "nestjs-inngest";

@Injectable()
export class ScheduledTasksService {
  // Daily cleanup at 2 AM UTC
  @CronFunction({
    id: "daily-cleanup",
    name: "Daily Cleanup Task",
    cron: "0 2 * * *",
    timezone: "UTC",
    retries: 2,
    timeout: 300000, // 5 minutes
    priority: 1, // High priority
  })
  async dailyCleanup() {
    // Cleanup logic here
    return { cleaned: true, timestamp: new Date() };
  }

  // Weekly report every Monday at 9 AM
  @CronFunction({
    id: "weekly-report",
    cron: "0 9 * * 1", // Monday 9 AM
    timezone: "America/New_York",
  })
  async weeklyReport() {
    // Generate weekly report
  }

  // High-frequency monitoring every 30 minutes
  @CronFunction({
    id: "health-check",
    cron: "*/30 * * * *", // Every 30 minutes
    timeout: 5000,
    retries: 1,
  })
  async healthCheck() {
    // Health monitoring logic
  }
}

Testing

Mock the InngestService for unit testing:

const mockInngestService = {
  send: jest.fn(),
  getClient: jest.fn(),
};

// Use in your test modules
providers: [{ provide: InngestService, useValue: mockInngestService }];

Key Concepts

@InngestFunction: Standard decorator for general-purpose event handling
@TypedInngestFunction: Type-safe decorator with strict TypeScript event validation
@OptimizedInngestFunction: Performance-optimized decorator for high-load applications
InngestService: Main service for sending events and creating integrations
- send() - Send events to Inngest
- getClient() - Get underlying Inngest client
- createServe(platform) - Create middleware/plugin integration
- createControllerHandler(platform) - Create controller-based integration
Step Functions: Use step.run(), step.sleep(), step.sendEvent() for reliable workflows
Events: Send events with { name: string, data: any } structure

Troubleshooting

Functions not registering: Ensure services are imported in your module and decorated with @Injectable()
Webhook errors: Verify signingKey configuration and endpoint URL
Debug mode: Set logger: true and isDev: true for detailed logging

Planned for Future Versions

Performance optimizations (connection pooling, memory management, request optimization)
Enhanced testing utilities and mocks
Typed function decorators (@TypedInngestFunction)
Advanced logging and monitoring
Circuit breakers and resilient error handling
Event sourcing and audit trails

License

MIT License - see CHANGELOG.md for version history.