Installation

Use whenyou are setting the package up for the first time, or lining up peer dependencies.

You getthe install command, a local NATS through Docker, and the version ranges that matter.

Get the package installed, NATS running locally, and the peer dependencies lined up. If you already have NATS, skip straight to Quick Start.

Install the package

npm

npm install @horizon-republic/nestjs-jetstream

pnpm

pnpm add @horizon-republic/nestjs-jetstream

Yarn

yarn add @horizon-republic/nestjs-jetstream

Peer dependencies

Required, and already present in any standard NestJS project:

• @nestjs/common, @nestjs/core, @nestjs/microservices: ^10.2.0 || ^11.0.0 || ^12.0.0
• reflect-metadata ^0.2.0
• rxjs ^7.8.0
• @opentelemetry/api ^1.9.0. The transport loads it whether or not tracing is on; without an OpenTelemetry SDK registered it does nothing. npm 7+ and pnpm install it with the package

Optional, install only for the feature that needs it:

• msgpackr ^1.11.0 || ^2.0.0 for the MessagePack codec
• @prometheus-io/client ^0.16.0, or prom-client ^15.0.0, its previous name, for Prometheus metrics

Runtime requirements

• Node.js >= 22.0.0
• TypeScript >= 5.7 (required by @nats-io/* v3 typed array generics), with moduleResolution set to node16, nodenext or bundler: the @nats-io/* v3 type declarations do not resolve under the legacy node10 setting
• NATS Server >= 2.10 with JetStream enabled; some features need a newer server, see below

NATS server versions

Measured against real servers. A feature used on an older server fails the boot, or the call, with a JetstreamCapabilityError, because those servers accept the settings and silently ignore them.

Feature	Minimum NATS	JetStream API level
Events, RPC, broadcast, ordered events, dead letters, health, metrics, tracing	2.10	none
Per-message TTL: ttl(), allow_msg_ttl	2.11	1
Scheduled messages: scheduleAt(), allow_msg_schedules, one-shot client.schedule({ at })	2.12	2
Recurring schedules: cron and intervals	2.14	4

In a cluster, upgrade every node before using a feature: the check reads the level of the server the client talks to, which says nothing about a stream leader still on an older node.

Server upgrades that need a config change

• NATS 2.15 caps a stream at 1000 consumers unless its config or the account sets max_consumers (server option jetstream.limits.default_max_consumers). Streams this library creates set max_consumers explicitly; a stream you provision yourself falls under the cap.
• NATS 2.16 switches acknowledgements to a new subject format. Subject permissions or account imports and exports that name $JS.ACK.<stream>.> or $JS.FC.<stream>.> stop matching: change them to $JS.ACK.> and $JS.FC.> before upgrading. The library reads acks through the client, so its code needs no change. See the NATS 2.15 upgrade notes.

Run NATS locally

The fastest way to get a JetStream-enabled NATS server running is with Docker:

docker run -d --name nats -p 4222:4222 nats:2.15 -js

This starts NATS on localhost:4222 with JetStream enabled (-js flag).

To verify it's running:

docker logs nats | head -5

NATS via Docker Compose for local development

docker-compose.yml

services:
  nats:
    image: nats:2.15
    command: -js
    ports:
      - "4222:4222"
      - "8222:8222" # monitoring

The monitoring port (8222) gives you access to the NATS monitoring endpoint for debugging.

What's next?

Once you have the package installed and NATS running, head to the Quick Start to wire up your first handlers.