Moleculer is a fast, modern, and powerful microservices framework for Node.js, designed to build efficient, reliable, and scalable distributed systems. It provides a comprehensive set of features including a promise-based request-reply mechanism, event-driven architecture, dynamic service discovery, load balancing, and fault tolerance capabilities like Circuit Breaker and Retry. The current stable version is 0.15.0, with frequent minor and patch releases, and major updates approximately annually, often introducing significant breaking changes. Key differentiators include its pluggable architecture for transporters (e.g., NATS, Redis, Kafka), serializers (e.g., MsgPack, CBOR), caching, loggers, and metrics/tracing reporters. It emphasizes a master-less architecture, making all nodes equal, and comes with built-in parameter validation and extensive TypeScript support.
npm install moleculerVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to create a basic Moleculer service, define actions and events, start the service broker, and then call an action and emit an event.
Upgrade your Node.js runtime to version 22 or newer. Ensure your deployment environment meets this requirement.
All nodes in your Moleculer cluster must be upgraded to v0.15.0 simultaneously to maintain communication. Consider a phased rollout with caution, or a complete upgrade of the entire microservices mesh.
Review your serialization strategy. Moleculer still supports pluggable serializers like JSON, JSONExt, MsgPack, CBOR, and Notepack. Migrate to one of these or implement a custom serializer as a plugin.
Always install the required peer dependency for any specific transporter, logger, or other module you configure. For example, if using `transporter: 'NATS'`, you must `npm install nats`.
Verify `"target": "es2017"` (or higher) and `"moduleResolution": "node"` or `"nodenext"` in your `tsconfig.json`. Consider adding `"lib": ["es2017", "esnext.asynciterable"]` for full type coverage.
Install the required package. For example, if using NATS, run `npm install nats` (or `yarn add nats`).
Ensure `broker.start()` has successfully resolved before making any calls or emits. Wrap your logic within the `.then()` block of `broker.start()` or ensure a running broker instance.
Verify the service name and action name are correct. Ensure the service is created with `broker.createService()` and the broker is started, allowing it to discover services across the network.