@horizon-republic/nestjs-jetstream

Ship reliable microservices with NATS JetStream and NestJS. Events, broadcast, ordered delivery, and RPC — with two lines of config.

Why this library?

NestJS ships with a NATS transport, but it's fire-and-forget. Messages vanish if no one's listening. This library adds JetStream — so your messages survive restarts, retry on failure, and replay for new consumers.

You keep writing @EventPattern() and @MessagePattern(). The library handles streams, consumers, and subjects automatically.

What's inside

Delivery modes — workqueue (one consumer), broadcast (all consumers), ordered (sequential), and dual-mode RPC (Core or JetStream-backed).

Operations — dead letter queue stream, health indicator for Kubernetes probes, graceful shutdown with drain, lifecycle hooks for observability.

Flexible — pluggable codecs (JSON/MsgPack/Protobuf), per-stream configuration, publisher-only mode for API gateways.

Quick Start

npm install @horizon-republic/nestjs-jetstream

// app.module.ts
@Module({
  imports: [
    JetstreamModule.forRoot({ name: 'orders', servers: ['nats://localhost:4222'] }),
    JetstreamModule.forFeature({ name: 'orders' }),
  ],
})
export class AppModule {}

// orders.controller.ts
@Controller()
export class OrdersController {
  constructor(@Inject('orders') private client: ClientProxy) {}

  @EventPattern('order.created')
  handle(@Payload() data: { orderId: number }) {
    console.log('Order created:', data.orderId);
  }

  @Get('emit')
  emit() {
    return this.client.emit('order.created', { orderId: 42 });
  }
}

// main.ts — wire the JetStream microservice transport into the HTTP app
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.connectMicroservice(
    { strategy: app.get(JetstreamStrategy) },
    { inheritAppConfig: true },
  );
  app.enableShutdownHooks();
  await app.startAllMicroservices();
  await app.listen(3000);
}
void bootstrap();

Documentation

Read the full documentation →

Section	What you'll learn
Getting Started	Installation, module setup, first handler
Messaging Patterns	RPC, Events, Broadcast, Ordered Events
Guides	Handler context, DLQ, health checks, performance tuning
Migration	From built-in NATS transport or between versions
API Reference	Full TypeDoc-generated API

License

MIT

JSPM