Moleculer logo

Moleculer

Moleculer is a fast, modern and powerful microservices framework for Node.js. It helps you to build efficient, reliable & scalable services. Moleculer provides many features for building and managing your microservices.

Website: https://moleculer.services

Documentation: https://moleculer.services/docs

Why Moleculer?

Moleculer gives you the distributed-systems layer as part of the framework, so you don't have to run a platform to get it:

No orchestrator required. Nodes find each other over the transporter (NATS, Redis, Kafka, MQTT, AMQP — or plain TCP with no broker at all). Service discovery is a built-in registry, not Consul, etcd or a service mesh.
Scale by starting another process. Every broker balances requests and events across the instances it can see (round-robin, random, CPU-usage, latency, sharding) with zero configuration.
Fault tolerance is a broker option. Timeout, retry, circuit breaker, bulkhead and fallback are configuration, not five more dependencies.
The same code from one process to many. Start as a modular monolith (transporter: null), split later by moving services to another process — the service code and the broker.call() sites stay the same.
Batteries included, and pluggable. Caching, parameter validation, metrics, tracing, serializers, loggers and middlewares all ship with it, and all of them can be swapped.

Top sponsors

What's included

Services and communication

Promise-based solution (async/await compatible)
request-reply concept
support event driven architecture with balancing
built-in service registry & dynamic service discovery
load balanced requests & events (round-robin, random, cpu-usage, latency, sharding)
master-less architecture, all nodes are equal
multiple services on a node/server
support versioned services
service mixins
support Streams

Reliability

many fault tolerance features (Circuit Breaker, Bulkhead, Retry, Timeout, Fallback)
built-in parameter validation with fastest-validator
pluggable parameter validator
built-in caching solution (Memory, MemoryLRU, Redis)

Observability

built-in metrics feature with reporters (Console, CSV, Datadog, Event, Prometheus, StatsD)
built-in tracing feature with exporters (Console, Datadog, Event, Jaeger, Zipkin, NewRelic)
pluggable loggers (Console, File, Pino, Bunyan, Winston, Debug, Datadog, Log4js)

Pluggable everything

plugin/middleware system
pluggable transporters (TCP, NATS, MQTT, Redis, Kafka, AMQP 0.9, AMQP 1.0)
pluggable serializers (JSON, JSONExt, MsgPack, CBOR, Notepack)
official API gateway, Database access and many other modules...

Installation

$ npm i moleculer

$ yarn add moleculer

Create your first microservice

This example shows you how to create a small service with an add action which can add two numbers and how to call it.

const { ServiceBroker } = require("moleculer");

// Create a broker
const broker = new ServiceBroker();

// Create a service
broker.createService({
    name: "math",
    actions: {
        add(ctx) {
            return Number(ctx.params.a) + Number(ctx.params.b);
        }
    }
});

// Start broker
broker.start()
    // Call service
    .then(() => broker.call("math.add", { a: 5, b: 3 }))
    .then(res => console.log("5 + 3 =", res))
    .catch(err => console.error(`Error occurred! ${err.message}`));

Try it in your browser

Scale it to another process

The interesting part is what happens when that service moves to its own process. Add a transporter, start the same file twice, and call it from a third process — no addresses to configure, no registry to run.

// node.js — the same service, now on its own node
const { ServiceBroker } = require("moleculer");

const broker = new ServiceBroker({
    nodeID: process.argv[2],
    transporter: "nats://localhost:4222"
});

broker.createService({
    name: "math",
    actions: {
        add(ctx) {
            return { result: Number(ctx.params.a) + Number(ctx.params.b), from: broker.nodeID };
        }
    }
});

broker.start();

// client.js — it only knows the action name
const { ServiceBroker } = require("moleculer");

const broker = new ServiceBroker({ nodeID: "client", transporter: "nats://localhost:4222" });

broker.start()
    .then(() => broker.waitForServices("math"))
    .then(async () => {
        for (let i = 0; i < 4; i++)
            console.log(await broker.call("math.add", { a: 5, b: 3 }));
        await broker.stop();
    });

$ node node.js node-1 &
$ node node.js node-2 &
$ node client.js
{ result: 8, from: 'node-1' }
{ result: 8, from: 'node-2' }
{ result: 8, from: 'node-1' }
{ result: 8, from: 'node-2' }

Stop one of the nodes and the calls keep working: the registry notices, and the surviving instance takes the traffic.

Create a Moleculer project

Use the Moleculer CLI tool to create a new Moleculer based microservices project.

Create a new project (named moleculer-demo)

$ npx moleculer-cli -c moleculer init project moleculer-demo

Open the project folder
```
$ cd moleculer-demo
```
Start the project
```
$ npm run dev
```
Open the http://localhost:3000/ link in your browser. It shows a welcome page that contains more information about your project & you can test the generated services.

:tada: Congratulations! Your first Moleculer-based microservices project is created. Read our documentation to learn more about Moleculer.

Welcome page

Examples

The moleculer-examples repository contains runnable projects, each with its own README and a run.sh that reproduces the whole demo:

Microservices without Kubernetes — one process → many processes → scaling a copy, with a moleculer-web gateway and a docker-compose deployment
Moleculer vs NestJS — the same service in both frameworks, side by side
TypeScript — shared contract file, schema style and class style, typed caller
From a modular monolith to microservices — extracting services in three stages
Service discovery and load balancing — scaling and crashes with traffic running, balancing strategies, TCP transporter
Circuit breaker, retry and timeout — the fault-tolerance features against a deliberately flaky service
Event-driven pub/sub — emit vs broadcast, groups, the same code on NATS, Redis and Kafka, durable channels
Moleculer vs gRPC vs tRPC — an RPC protocol compared with a service layer, and how to combine them

Plus two full applications: a blog site and the RealWorld backend.

Official modules

We have many official modules for Moleculer. Check our list!

Supporting

Moleculer is an open source project. It is free to use for your personal or commercial projects. However, developing it takes up all our free time to make it better and better on a daily basis. If you like Moleculer framework, please support it.

Thank you very much!

For enterprise

Available as part of the Tidelift Subscription.

The maintainers of moleculer and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Documentation

You can find here the documentation.

Changelog

See CHANGELOG.md.

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

Contributions

We welcome you to join in the development of Moleculer. Please read our contribution guide.