Skip to content

nestjs-amqp

NestJS microservices that talk over RabbitMQ, with an HTTP and WebSocket gateway in front.

MITTypeScriptActiveVersion 3.2.0

What it's for

When an application is split into many small services, they need a dependable way to talk to each other and to the outside world. With NestJS and RabbitMQ that usually means hand-writing queues, exchanges, RPC replies, reconnects and a gateway that turns HTTP calls into messages, with authentication and permissions on top. We put all of that into nestjs-amqp, one library for NestJS 11: each service is a few decorators, the topology lives in a YAML file, and the gateway is configured rather than written. We develop it on GitHub and publish it on npm under the MIT license.

Installation

npm i @open-rlb/nestjs-amqp

Example

import { Injectable } from '@nestjs/common';
import { BrokerAction, BrokerParam } from '@open-rlb/nestjs-amqp';

@Injectable()
export class OrdersService {
  // (topic, action) = ('orders', 'order.create') — unique across the app
  @BrokerAction('orders', 'order.create', 'rpc')
  create(
    @BrokerParam('header', 'X-GTW-AUTH-USERID') userId: string, // one header
    @BrokerParam('body', 'sku') sku: string,                    // one body field
    @BrokerParam('body-full') payload: any,                     // whole body
    @BrokerParam('action') action: string,                      // the action string
  ) {
    return { ok: true, userId, sku, action };
  }
}

What it does

Decorators and one YAML file

A method marked with @BrokerAction becomes an action on RabbitMQ, callable as RPC or as an event: the library finds it at startup and wires it to its queue. You declare exchanges, queues, topics and routes in a YAML file, and at startup the library creates or checks the exchanges, queues and bindings.

HTTP and WebSocket gateway

Each HTTP route leads to an action on the broker, and errors from the services come back with the right status (400, 401, 403, 404, 500). Broker events reach WebSocket clients or a webhook, even with several gateway instances running.

Access and permissions

Any route or event can require a JWT or JWKS token: the gateway checks it and passes the user's details to the services in headers the request can't overwrite. An optional ACL module decides which actions a user holds on a resource, and WebSocket events can be scoped so each client only gets its own data.

When something goes wrong

A failing message gets at most 5 attempts (the default), then it can go to a dead-letter queue if you set one up, instead of looping forever. Publishing waits for the broker to confirm, the connection reopens on its own, and on shutdown a service stops taking messages and finishes the work in progress, with a 25-second limit.

Routes that keep themselves current

At startup a service can announce its own HTTP routes: the gateway applies only what changed, logs it, and reloads without a restart. An optional module keeps routes and auth providers in a database, with request metrics and a /health probe.

Ready with one command

The nest add @open-rlb/nestjs-amqp command sets up AppModule, main.ts and config.yaml, with or without the gateway, and copies seven Claude Code skills into the project to help add actions, routes, events and permissions. Another 16 schematics change the config one piece at a time: a route, a topic, a queue, the retry policy.

Requirements

  • NestJS 11
  • A reachable RabbitMQ server
  • Also in the project: @nestjs/config, @nestjs/axios and js-yaml; @nestjs/platform-ws if you use the gateway
  • For the ACL and gateway-admin modules, a database and cache of your choice, wired in by the application (the samples use MongoDB or memory)

The code, releases and issues are on GitHub.