NATS JetStream NestJS App

Simple NestJS application that bootstraps a reusable NATS connection using the official modern NATS.js Node transport package.

What this project demonstrates

• NestJS HTTP application
• Global environment configuration using @nestjs/config
• Local NATS server with JetStream enabled using Docker Compose
• One shared NATS connection per NestJS application instance
• Core NATS service
• Demo service for see NATS behavior
• Basic health endpoint for checking NATS connection state
• Graceful shutdown hooks
• Unit tests for controller and service code
• ESLint setup

Structure

src/
├── modules/demos/core-nats/      # HTTP-triggered learning demos
├── modules/health/               # health endpoint
├── infrastructure/nats/          # reusable NATS connection + CoreNatsService
├── shared/interfaces/
└── shared/config

Run locally

docker compose up -d
npm run start:dev

Health check:

GET http://localhost:3000/health

Run Core NATS demos

Run all demos:

curl -X POST http://localhost:3000/demos/core-nats/all

Run one demo:

curl -X POST http://localhost:3000/demos/core-nats/exact
curl -X POST http://localhost:3000/demos/core-nats/star
curl -X POST http://localhost:3000/demos/core-nats/greater-than
curl -X POST http://localhost:3000/demos/core-nats/fan-out
curl -X POST http://localhost:3000/demos/core-nats/at-most-once

Queue Group demo APIs:

curl -X POST http://localhost:3000/demos/core-nats/queue-group/jobs
curl -X POST http://localhost:3000/demos/core-nats/queue-group/jobs/batch

Normal subscribers all receive one message. Queue Group subscribers using the same subject and demo-workers group compete, so each message is handled by one group member.

Tests and checks

Tests are unit tests and do not require a real NATS server. Running the HTTP demos still requires NATS from Docker Compose.

npm test -- --runInBand
npm run lint
npm run build

Environment

Copy .env.example to .env if needed.