Moleculer — Progressive Microservices Framework for Node.js

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