NATS

Why NATS

NATS is a cloud-native messaging system written in Go. The server is a single ~20MB binary. Core characteristics:

• 1M+ messages/sec on modest hardware
• Sub-millisecond latency
• Subjects are strings with wildcards (>, *)
• No per-message routing config — subjects are the routing
• JetStream adds persistence, at-least-once delivery, and KV store on top

Use NATS when you want Kafka-level throughput with dramatically simpler operations.

Running NATS

# Single node — local dev
docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:latest

# With JetStream enabled
docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:latest -js

# 3-node cluster (docker-compose)
services:
  nats1:
    image: nats:latest
    command: -p 4222 -cluster nats://0.0.0.0:6222 -routes nats://nats2:6222,nats://nats3:6222 -js -sd /data
    ports: ["4222:4222"]
    volumes: ["nats1:/data"]

  nats2:
    image: nats:latest
    command: -p 4222 -cluster nats://0.0.0.0:6222 -routes nats://nats1:6222,nats://nats3:6222 -js -sd /data
    ports: ["4223:4222"]
    volumes: ["nats2:/data"]

  nats3:
    image: nats:latest
    command: -p 4222 -cluster nats://0.0.0.0:6222 -routes nats://nats1:6222,nats://nats2:6222 -js -sd /data
    ports: ["4224:4222"]
    volumes: ["nats3:/data"]

Core Pub/Sub

import { connect, StringCodec } from 'nats';

const nc = await connect({ servers: 'nats://localhost:4222' });
const sc = StringCodec();

// Subscribe
const sub = nc.subscribe('orders.created');
(async () => {
	for await (const msg of sub) {
		const order = JSON.parse(sc.decode(msg.data));
		console.log('Order received:', order.id);
	}
})();

// Publish
nc.publish(
	'orders.created',
	sc.encode(
		JSON.stringify({
			id: 'ord-123',
			customerId: 'cust-456',
			total: 99.99
		})
	)
);

Subject wildcards:

• orders.* — matches orders.created, orders.cancelled but not orders.payment.failed
• orders.> — matches orders.created, orders.payment.failed, any depth

Core pub/sub is fire-and-forget — if no subscriber is listening when you publish, the message is gone. Use JetStream for persistence.

JetStream Streams

JetStream stores messages in streams with configurable retention:

import { connect, JSONCodec, RetentionPolicy, StorageType } from 'nats';

const nc = await connect({ servers: 'nats://localhost:4222' });
const js = nc.jetstream();
const jsm = await nc.jetstreamManager();
const jc = JSONCodec();

// Create stream — subjects it captures
await jsm.streams.add({
	name: 'ORDERS',
	subjects: ['orders.>'],
	retention: RetentionPolicy.Limits,
	storage: StorageType.File,
	max_age: 7 * 24 * 60 * 60 * 1e9, // 7 days in nanoseconds
	max_msgs: -1, // unlimited
	num_replicas: 3, // replicate across 3 nodes
	duplicate_window: 2 * 60 * 1e9 // 2-minute deduplication window
});

// Publish to stream
await js.publish(
	'orders.created',
	jc.encode({ id: 'ord-123', customerId: 'cust-456' }),
	{ msgID: 'ord-123' } // deduplication key
);

JetStream Consumers

// Push consumer — server pushes to a subject
const pushConsumer = await jsm.consumers.add('ORDERS', {
	durable_name: 'payment-service', // named = durable = remembers position
	deliver_subject: '_INBOX.payments', // server pushes here
	deliver_policy: DeliverPolicy.New, // start from new messages only
	ack_policy: AckPolicy.Explicit, // must ack each message
	max_deliver: 5, // retry up to 5 times
	ack_wait: 30 * 1e9, // 30s to ack before redeliver
	filter_subject: 'orders.created' // only this subject
});

// Pull consumer — consumer requests batches (preferred for workers)
const pullConsumer = await jsm.consumers.add('ORDERS', {
	durable_name: 'analytics',
	ack_policy: AckPolicy.Explicit,
	filter_subject: 'orders.>'
});

// Pull a batch
const messages = await js.fetch('ORDERS', 'analytics', { batch: 100, expires: 5000 });
for await (const msg of messages) {
	const order = jc.decode(msg.data);
	await processForAnalytics(order);
	msg.ack();
}

Work Queues (Competing Consumers)

JetStream work queues: each message delivered to exactly one consumer in the group.

// Create work queue stream
await jsm.streams.add({
	name: 'EMAIL_JOBS',
	subjects: ['jobs.email.>'],
	retention: RetentionPolicy.WorkQueue, // delete on ack
	storage: StorageType.File,
	num_replicas: 3
});

// Multiple workers consume from same durable consumer
// Each message goes to exactly one worker
await jsm.consumers.add('EMAIL_JOBS', {
	durable_name: 'email-workers',
	ack_policy: AckPolicy.Explicit,
	max_ack_pending: 50 // max outstanding unacked per consumer
});

// Worker process (run multiple instances)
const consumer = await js.consumers.get('EMAIL_JOBS', 'email-workers');
const iter = await consumer.consume({ max_messages: 10 });

for await (const msg of iter) {
	await sendEmail(jc.decode(msg.data));
	msg.ack();
}

KV Store

JetStream includes a distributed key-value store:

const kv = await js.views.kv('config', {
	ttl: 3600 * 1e9, // 1 hour TTL
	replicas: 3
});

// Put
await kv.put('feature-flags', jc.encode({ darkMode: true, newCheckout: false }));

// Get
const entry = await kv.get('feature-flags');
const flags = jc.decode(entry.value);

// Watch for changes (reactive config)
const watcher = await kv.watch({ key: 'feature-flags' });
for await (const entry of watcher) {
	const flags = jc.decode(entry.value);
	updateFeatureFlags(flags);
}

This replaces Consul KV or Redis for distributed config — you get change notifications, history, and TTL built in, all on the same NATS cluster your messaging uses.

Request-Reply

NATS has built-in request-reply — no setup needed:

// Server
nc.subscribe('user.lookup', {
	callback: async (err, msg) => {
		const { userId } = jc.decode(msg.data);
		const user = await db.findUser(userId);
		msg.respond(jc.encode(user));
	}
});

// Client
const response = await nc.request('user.lookup', jc.encode({ userId: '123' }), { timeout: 5000 });
const user = jc.decode(response.data);

NATS handles the correlation and reply routing automatically. The client blocks until the server responds or the timeout fires.

Monitoring

# NATS monitoring HTTP API (port 8222)
curl http://localhost:8222/varz      # server stats
curl http://localhost:8222/connz     # connections
curl http://localhost:8222/jsz       # JetStream stats
curl http://localhost:8222/subsz     # subscriptions

# JetStream stream status
nats stream info ORDERS
nats consumer info ORDERS payment-service

# Consumer lag
nats consumer ls ORDERS
# Shows pending messages (lag) per consumer

Prometheus metrics via nats-server built-in exporter (enable with -m 8222), scraped by nats_prometheus_exporter.

When to Use NATS Over Kafka

Use NATS when:

• You want a single binary to deploy and operate
• You need request-reply as a first-class primitive
• Your throughput requirements are < 1M msg/sec per node
• You want the KV store for config alongside messaging
• Operational simplicity matters more than Kafka’s ecosystem

Use Kafka when:

• You need long-term event retention (weeks/months)
• You’re building stream processing (Kafka Streams, Flink)
• You need the Kafka Connect ecosystem (hundreds of connectors)
• Your team already knows Kafka
• Log compaction is a primary requirement