Nats

# NATS API Skill

## Quick Start
NATS is an extremely high-performance messaging system (Pub/Sub, Request/Reply, JetStream). Use the `nats` package for Node.js to communicate.

```bash
npm install nats
```

## Common Workflows
### JetStream Persistence
Standard NATS is ephemeral (fire-and-forget). For guaranteed delivery and message replay, use JetStream. Create a Stream, publish messages to it, and consume them using durable consumers.

## Production Patterns
### Request-Reply Architecture
Replace internal REST microservices with NATS Request-Reply. Service A sends a request to a subject `orders.create`; Service B processes it and replies on a unique inbox subject. This decouples services and enables load balancing automatically.

## Error Recovery
NATS handles reconnections automatically. However, if a message publication to JetStream fails (e.g., `NoResponders`), catch the error and queue it locally or utilize an exponential backoff retry mechanism.

## Security Notes
Use NATS Decentralized Auth (NKEYS). Never pass plaintext passwords. Issue scoped credentials to services, restricting which subjects they can publish or subscribe to.

## Performance Considerations
NATS can process millions of messages per second. Avoid processing messages sequentially in tight loops; utilize asynchronous handlers to prevent blocking the Node.js event loop.

## Testing Guidance
Spin up a local NATS server binary (`nats-server`) or Docker container in your CI/CD pipeline. It boots in milliseconds and consumes negligible RAM.

## Troubleshooting
If consumers aren't receiving messages in a JetStream, verify that the subject they are listening to exactly matches the subjects bound to the underlying Stream configuration.

## References
- [NATS Documentation](https://docs.nats.io/)

## Related Skills
- [Kafka](/skills/kafka)
- [Redis](/skills/redis)

## Why use this skill
Use this when your agent works with **nats** — structured patterns beat pasted docs and prevent common hallucinations.

## AI pitfalls
- Using outdated SDK or API versions from training data
- Inventing environment variable names
- Omitting error handling and retry logic

## Production checklist
- [ ] Secrets in environment variables, not source code
- [ ] Error handling and logging in place
- [ ] Rate limits and timeouts configured

## Related skills
- [`kafka`](../kafka/SKILL.md) — related to
- [`redis`](../redis/SKILL.md) — related to

---
> **Last Verified:** 2026-07-02