@relab/nestjs-kafka

Purpose

This package provides helpers for integrating Kafka with NestJS microservices. It simplifies Kafka client/consumer/producer configuration, resilient consumer restart strategy, and subscription behavior, so you can focus on your business logic.

Key Features

• Simple setup: One call to configure a Kafka microservice transport in your NestJS app.
• Resilient consumption: Automatic consumer restart with backoff after failures.
• Configurable logging: Uses kafkajs log levels and a structured log creator.
• Producer defaults: Sensible producer defaults (default partitioner, no auto topic creation).

Installation

pnpm add @relab/nestjs-kafka

Usage

Consumer

main.ts

import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'
import { configureKafkaMicroservice } from '@relab/nestjs-kafka'

async function bootstrap() {
    const app = await NestFactory.create(AppModule)

    await configureKafkaMicroservice(app, {
        clientId: 'my-service',
        brokers: ['localhost:9092'],
        consumerGroup: 'my-service-consumers',
        restartTimeout: 60_000,     // ms
        fromBeginning: true,        // optional
    })

    await app.startAllMicroservices()
    await app.listen(3000)
}

bootstrap()

Producer

Use NestJS ClientKafka or your own kafkajs producer as needed. This package focuses on configuring the microservice transport for consumers; it does not provide a custom producer factory.

API

configureKafkaMicroservice(app, options)

Configures your NestJS app to use Kafka as a microservice transport and applies resilient consumer restart behavior and sensible defaults.

Parameters

• app: INestApplication — Your NestJS application instance.
• options: object
  • clientId (string, optional): Kafka client ID (defaults to host name).
  • brokers (string[], required): Kafka broker addresses, e.g. ['localhost:9092'].
  • consumerGroup (string, required): Kafka consumer group ID.
  • logLevel (KafkaLogLevel, optional): kafkajs log level (default: INFO).
  • restartTimeout (number, required): Pause (ms) before restarting the consumer after a failure.
  • fromBeginning (boolean, optional, default: true): Subscribe from the beginning on first subscription.

How it works

• Kafka client setup: Configures client ID, brokers, structured logging, and log level.
• Consumer config: Sets group, session/heartbeat timeouts, disables auto topic creation, and enables a retry strategy with automatic restart after failures (waiting restartTimeout).
• Producer config: Uses the default partitioner and disables auto topic creation.
• Subscription: Subscribes with fromBeginning on first subscription by default.

Advanced

You can import the following for custom setups:

• configureKafkaMicroservice: Helper to attach a Kafka microservice transport to your NestJS app with resilient defaults.

License

MIT