@relab/nestjs-rabbit-mq

Purpose

This package provides helpers for integrating RabbitMQ with NestJS microservices. It simplifies queue setup, message acknowledgement, error handling, and dead-letter/reprocessing logic, so you can focus on your business logic.

Key Features

• Automatic queue setup: Ensures main, reprocess, and dead-letter queues are created with correct options.
• Message acknowledgement: Automatically acknowledges messages on success, nacks on error, and moves messages to DLQ after max attempts.
• Re-processing logic: Failed messages are retried via a reprocess queue before being sent to a dead-letter queue.
• Configurable retry and queue options.

Installation

pnpm add @relab/nestjs-rabbit-mq

Usage

Consumer

main.ts

import { configureRabbitMqMicroservice } from '@relab/nestjs-rabbit-mq'

const app = /* create nestjs app */

await configureRabbitMqMicroservice(app, {
    connectionString: '<connection string>',
    maxAttempts: 3,
    queue: {
        name: '<queue_name>',
        durable: true,
        reprocessTimeout: 30_000,      // optional, ms
        deadLetterTimeout: 48 * 60 * 60 * 1000, // optional, ms
        forceCreate: false,            // optional
    },
})

Producer

module.ts

import { configureRabbitMqMicroservice } from '@relab/nestjs-rabbit-mq'

@Module({
    providers: [
        {
            provide: 'SMS_SERVICE',
            useFactory: (traceContextService: TraceContextService) => {
                return RabbitMqClientProxyFactory.create({
                  connectionString: 'amqp://user:password@localhost:5672'
                  queueName: 'queue1',
                  traceContextService
                })
            },
        },
    ],
    exports: [],
})
export class Module {}

API

configureRabbitMqMicroservice(app, options)

Configures your NestJS app to use RabbitMQ as a microservice transport, sets up the required queues, and installs global message acknowledgement logic.

Parameters

• app: INestApplication — Your NestJS application instance.
• options: object
  • connectionString (string, required): RabbitMQ connection string.
  • maxAttempts (number, optional, default: 3): Max delivery attempts before moving message to DLQ.
  • queue (object, required):
    • name (string, required): Name of the main queue.
    • durable (boolean, optional): Whether the queue survives broker restarts.
    • reprocessTimeout (number, optional, default: 30000): Time (ms) before a message in the reprocess queue is retried.
    • deadLetterTimeout (number, optional, default: 48h): Time (ms) before a message in the DLQ is discarded.
    • forceCreate (boolean, optional): If true, deletes and recreates queues if their options do not match.

How it works

• Queue Setup: Three queues are created per logical queue:
  • <queue_name>: Main queue.
  • <queue_name>_rlq: Reprocess letter queue (for retrying failed messages).
  • <queue_name>_dlq: Dead letter queue (for messages that exceeded max attempts).
• Message Flow:
  1. On handler success, message is acknowledged.
  2. On handler error, message is nacked. If delivery attempts exceed maxAttempts, it is moved to the DLQ.
  3. Messages in the reprocess queue are retried after reprocessTimeout.
  4. Messages in the DLQ are retained for deadLetterTimeout.

Advanced

You can also use the following exports for custom setups:

• RabbitMQAckInterceptor: The interceptor responsible for ack/nack logic.
• setupQueue(connectionString, queueName, options): Manually set up queues.

License

MIT