# Moleculer — Progressive Microservices Framework for Node.js

> Build scalable microservices with built-in service discovery, load balancing, and fault tolerance. Moleculer provides a convention-driven framework for Node.js that handles inter-service communication, caching, and event-driven architecture out of the box.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Moleculer — Progressive Microservices Framework for Node.js

## Quick Use
```bash
npm install moleculer
npx moleculer init project my-service
cd my-service && npm run dev
```

## Introduction
Moleculer is a progressive microservices framework for Node.js that provides everything needed to build distributed systems without external infrastructure dependencies. It includes built-in service discovery, request-response and event-driven communication, load balancing, circuit breakers, and caching in a batteries-included package.

## What Moleculer Does
- Provides service discovery and inter-service communication without external service mesh
- Handles load balancing across service instances with multiple strategies (round-robin, random, CPU-based)
- Includes built-in circuit breaker, retry, timeout, and bulkhead patterns for fault tolerance
- Supports multiple transport protocols (NATS, Redis, AMQP, MQTT, TCP) for service messaging
- Offers request-level caching, parameter validation, and metrics collection out of the box

## Architecture Overview
Moleculer organizes applications into services, each containing actions (request-response handlers), events (pub/sub handlers), and lifecycle hooks. A ServiceBroker instance on each node manages local services and handles communication with remote nodes via a configurable transporter. Nodes discover each other through the transporter layer and exchange heartbeats to maintain a distributed service registry. When a node calls a remote action, the broker serializes the request, routes it through the transporter to an available instance, and deserializes the response, all transparently to the calling code.

## Self-Hosting & Configuration
- Initialize projects with the CLI wizard or manually by creating a `moleculer.config.js` file
- Configure the transporter (NATS, Redis, TCP, etc.) for inter-node communication
- Define services as classes or objects with actions, events, and lifecycle methods
- Deploy multiple instances of services across nodes for horizontal scaling
- Use the built-in API Gateway service to expose actions as REST or GraphQL endpoints

## Key Features
- Zero-config service discovery and automatic load balancing between instances
- Pluggable architecture with swappable transporters, serializers, cachers, and validators
- Built-in API Gateway for exposing services via REST, WebSocket, or GraphQL
- Distributed event bus with balanced and broadcast event delivery modes
- Middleware system for request/response pipeline customization (logging, auth, tracing)

## Comparison with Similar Tools
- **NestJS** — opinionated Node.js framework with microservice support; Moleculer focuses exclusively on microservices with deeper built-in distributed systems patterns
- **Seneca** — lightweight microservices toolkit; Moleculer provides more built-in features (caching, metrics, circuit breakers) without additional plugins
- **Dapr** — language-agnostic sidecar runtime; Moleculer is Node.js-native with tighter integration and no sidecar overhead
- **gRPC** — efficient RPC protocol; Moleculer provides a higher-level framework around service communication with built-in resilience patterns
- **Express + custom microservices** — manual setup of discovery, balancing, and resilience; Moleculer handles all of these declaratively

## FAQ
**Q: Can Moleculer services communicate across different programming languages?**
A: Moleculer is primarily a Node.js framework, but it communicates via standard message brokers (NATS, Redis, AMQP). Non-Node.js services can participate by implementing the Moleculer protocol on a supported transporter.

**Q: How does Moleculer handle service versioning?**
A: Services can be versioned by setting a version property. Multiple versions can run simultaneously and clients specify which version to call, enabling gradual migrations.

**Q: What happens when a service instance crashes?**
A: The circuit breaker detects failures and stops routing to unhealthy instances. The service registry removes nodes that miss heartbeats. Remaining healthy instances continue serving requests.

**Q: Can I run all services in a single process during development?**
A: Yes. Moleculer supports running multiple services in one broker instance for development, then distributing them across nodes in production without code changes.

## Sources
- https://github.com/moleculerjs/moleculer
- https://moleculer.services/docs

---
Source: https://tokrepo.com/en/workflows/moleculer-progressive-microservices-framework-node-js-bacb199a
Author: AI Open Source