# Moleculer: a Node.js microservices framework with the registry built in

> Moleculer puts service discovery, load balancing and fault tolerance inside the broker instead of asking you to run Consul or a service mesh. It suits Node.js teams that want to start as a monolith and split later.

**moleculerjs/moleculer** — :rocket: Progressive microservices framework for Node.js

- Repository: https://github.com/moleculerjs/moleculer
- Website: https://moleculer.services/
- Stars: 6,378 · Forks: 604
- Language: JavaScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/moleculerjs-moleculer

## The problem Moleculer removes: no orchestrator, no separate registry

Most microservice stacks make you assemble the distributed-systems layer yourself. You run Consul or etcd for discovery, a message broker for transport, a sidecar or mesh for balancing, and a library for retries. Moleculer's README states the framework instead gives you that layer as part of the framework, so you do not have to run a platform to get it. Nodes find each other over the transporter, and service discovery is a built-in registry rather than Consul, etcd or a service mesh.

The audience is narrow and specific: Node.js developers. The package is published as moleculer on npm, the main entry is index.js with an ESM build at index.mjs, and the repository ships TypeScript definitions at index.d.ts. If your services are not JavaScript, the registry, transporters and middlewares here are not reachable from your runtime, so the framework's main selling point does not apply to you.

The second audience is teams that are not ready to commit to distribution. The README describes starting as a modular monolith with transporter: null and splitting later by moving services to another process, with the service code and the broker.call() sites staying the same. That is a migration story, not a deployment story, and it is the strongest argument in the project's favour.

## How the broker, registry and transporter fit together

A Moleculer application is built around a ServiceBroker. You construct one, call broker.createService() to register services with named actions, and call broker.start(). Actions are invoked by name through broker.call("math.add", { a: 5, b: 3 }), which returns a promise. The README calls this the request-reply concept, and the same broker also supports event-driven architecture with balancing.

The architecture is master-less: all nodes are equal, and there is no coordinator to elect or lose. When you give the broker a transporter, each node advertises its services to the others and the built-in registry tracks who offers what. Load balancing across the instances a broker can see is described as working with zero configuration, using round-robin, random, CPU-usage, latency or sharding strategies. Because discovery lives in the broker, there is no address list to maintain and no registry process to run.

Reliability is expressed as broker configuration rather than as separate dependencies. The README lists timeout, retry, circuit breaker, bulkhead and fallback as fault-tolerance features, and parameter validation through fastest-validator, which is pluggable. Observability follows the same pattern: metrics with Console, CSV, Datadog, Event, Prometheus and StatsD reporters, tracing with Console, Datadog, Event, Jaeger, Zipkin and NewRelic exporters, and loggers including Console, File, Pino, Bunyan, Winston, Debug, Datadog and Log4js.

The trade-off is visible in that list. Every one of those capabilities runs inside the Node.js process. A slow action, an exhausted event loop or a memory-hungry service affects the same runtime that hosts the registry client and the transporter connection. A sidecar-based mesh moves that concern out of your process; Moleculer does not.

## Installing Moleculer and calling your first action

The README gives two install commands. Either works; pick the one that matches your lockfile. The package name is moleculer and no global install is required.

```bash
npm i moleculer
```

```bash
yarn add moleculer
```

After installation, the README's first example creates a broker, registers a single service named math with one add action, starts the broker and calls the action. The call resolves with the numeric result, so the console line prints 5 + 3 = 8.

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

const broker = new ServiceBroker();

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

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

Note that no transporter is set here. This is the single-process case the README calls the modular monolith, and it is the right place to start. The repository also ships runnable examples under examples/, including examples/math.service.js, examples/simple/ and examples/client-server/, plus a demo script wired to examples/index.js.

The second step is distribution. The README shows the same service given a nodeID and a transporter pointing at nats://localhost:4222, and a separate client process that knows only the action name. The client's broker is created with nodeID: "client" and the same transporter string. Start the service file twice and the client once, and the client reaches whichever instance the registry reports. The README's client example is truncated at the final call, so treat the service-side snippet as the complete reference and write the client call yourself as broker.call("math.add", { a: 5, b: 3 }).

## Where Moleculer is the wrong choice

The framework assumes every participant speaks Moleculer. A node discovers services through the built-in registry over the transporter, so a Go or Python service that publishes to the same NATS or Kafka broker is not a Moleculer service and will not appear in the registry. Teams with polyglot fleets get partial coverage: Moleculer nodes see each other, and everything else needs its own integration path.

Running the registry in-process also means a misbehaving service can degrade discovery for its neighbours. There is no separate control plane to absorb that. If your requirement is that a crashing service must not affect the routing layer, the master-less design is a liability rather than a feature.

The README does not document rollback, version-skew handling between nodes, or what happens when two nodes advertise the same service name and version during a rolling deploy. Versioned services and service mixins are listed as features, but the README does not explain the upgrade sequence. Treat that as an open question to answer from the documentation site before you plan a release.

Finally, the project's own description calls it progressive, and the feature list is long. Caching, validation, metrics, tracing, serializers, loggers and middlewares all ship in the box. That is convenient at the start and a surface area to maintain later. A team that wants a thin transport library and nothing else will spend time disabling defaults.

## Moleculer compared with a sidecar service mesh

The closest alternative in spirit is a service mesh such as Istio or Linkerd. The difference is where the logic lives. A mesh puts discovery, balancing, retries and mTLS into a sidecar proxy next to each pod, so the application code stays unaware and the guarantees apply to any language. Moleculer puts the same concerns into the broker library inside your Node.js process, so there is no proxy to deploy and no per-pod overhead, but the guarantees only apply to Moleculer services.

The operational difference is what you run. A mesh requires a control plane, sidecar injection and a Kubernetes-style platform. Moleculer requires a transporter, which can be NATS, Redis, Kafka, MQTT, AMQP 0.9, AMQP 1.0, or plain TCP with no broker at all. The README explicitly notes that plain TCP works without a broker, which is the lowest-friction option for a small deployment and one a mesh cannot match.

If you already run Kubernetes and need uniform policy across many languages, a mesh is the better fit and Moleculer adds a second, narrower layer. If your services are Node.js and you want request-reply, events and fault tolerance without operating a control plane, the broker-in-process model removes real infrastructure. The two are not mutually exclusive, but running both means two places to configure timeouts and retries.

## Maintenance, versions and the MIT licence

The repository is not archived, and the last push was on 2026-09-07. Two release lines were published on 2026-08-29: v0.15.2 and v0.14.36. The v0.15.1 release came earlier, on 2026-07-21. The existence of a maintained 0.14 line alongside 0.15 means you should decide deliberately which line you pin; the README does not state how long 0.14 will continue to receive releases, so that is a question for the maintainers rather than something the README answers.

Upgrade cost is hard to estimate from the repository alone. The README does not publish a breaking-change policy or a migration guide for the 0.14 to 0.15 step, and CHANGELOG.md is the file to read before moving. The package.json exposes a single main entry, index.js, with an ESM wrapper at index.mjs and types at index.d.ts, so the public surface is one module. The lockfile, package-lock.json, is committed.

Moleculer is MIT licensed. In practical terms that permits commercial and closed-source use, modification and redistribution provided the copyright notice and permission notice are included, and it comes with no warranty. That is the usual reading of MIT, not legal advice; if your organisation has a licence review process, run it. Note that the framework has optional integrations with third-party services such as Datadog, Prometheus, Jaeger, Zipkin and NewRelic through reporters and exporters; those are separate products with their own terms, and the MIT licence on moleculer does not extend to them.

## Conclusion

Adopt Moleculer if your team writes Node.js, wants request-reply and event-driven services without operating Consul, etcd or a service mesh, and values being able to run the same service code in one process (transporter: null) before splitting it across nodes. Do not adopt it if your services are not JavaScript: the broker is a Node.js library, and the registry, transporters and middlewares are all in-process. Do not adopt it either if you need a broker-agnostic mesh that also covers Go, Java or Python services, because Moleculer nodes only see other Moleculer nodes. Before committing, verify three things in your own environment: that your chosen transporter (NATS, Redis, Kafka, MQTT, AMQP or plain TCP) is one the framework actually ships, that the fault-tolerance settings you intend to rely on (timeout, retry, circuit breaker, bulkhead, fallback) behave the way the documentation describes under your load, and that the version you pin is v0.15.2 rather than the older v0.14.36 line, since both were published on 2026-08-29.

## FAQ

### What is Moleculer?

Moleculer is a microservices framework for Node.js. It provides a ServiceBroker that handles request-reply calls, events, a built-in service registry, load balancing and fault-tolerance features such as timeout, retry, circuit breaker, bulkhead and fallback.

### How do I install Moleculer?

The README gives two commands: npm i moleculer or yarn add moleculer. No global install or CLI download is required, and the package is published on npm under the name moleculer.

### Can I use Moleculer with TypeScript?

Yes. The repository ships type definitions at index.d.ts, referenced from the types field in package.json, and the examples directory contains a typescript folder with a runnable demo wired to the demo:ts script.

### Does Moleculer require a separate service registry like Consul or etcd?

No. The README states that service discovery is a built-in registry rather than Consul, etcd or a service mesh, and that nodes find each other over the transporter. The transporter can be NATS, Redis, Kafka, MQTT, AMQP 0.9, AMQP 1.0, or plain TCP with no broker at all.

### Can a Moleculer service run in a single process before being split out?

Yes. The README describes starting as a modular monolith with transporter: null and splitting later by moving services to another process, with the service code and the broker.call() sites staying the same.

## Sources

- [License: MIT](https://github.com/moleculerjs/moleculer/blob/master/LICENSE)
- [moleculerjs/moleculer on GitHub](https://github.com/moleculerjs/moleculer)
- [Project website](https://moleculer.services/)
- [README](https://github.com/moleculerjs/moleculer/blob/master/README.md)
- [Releases](https://github.com/moleculerjs/moleculer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/moleculerjs-moleculer