DEV Community: Icebob

Service discovery and load balancing in Node.js — without Consul or Kubernetes

Icebob — Tue, 29 Sep 2026 13:00:21 +0000

The moment you run a service on more than one machine, two questions appear that a monolith never had to answer: where is it (service discovery) and which copy do I call (load balancing). The standard answers are all infrastructure. A registry like Consul or etcd plus a client library in every service. Kubernetes Service objects plus kube-proxy. A service mesh sidecar next to every pod. An nginx or HAProxy in front of every pool.

Each of these works. Each is also a component you run, monitor, upgrade and get paged for, and none of them knows anything about your application — they see IP addresses and ports, not "the orders.create action, version 2, currently on three nodes".

This article shows the other approach: put the registry in the framework. Every Node.js process keeps a full copy of the service catalogue, learns about changes directly from its peers, and picks the target of each call locally. No registry server, no sidecar, no extra hop. I'll use Moleculer, which has done it this way since 2017, and I'll run every scenario for real — including the one where a node is killed with SIGKILL mid-traffic — so you can see exactly what happens and when.

How it works, in one paragraph

Each process runs a service broker (the Moleculer runtime) with a node ID. When a broker starts, it publishes an INFO packet on the transporter (the message bus — NATS here, but Redis, MQTT, AMQP, Kafka or plain TCP work the same) describing every service, action and event it hosts, plus free-form metadata. Every other broker receives it and updates its local registry. Brokers send a heartbeat every few seconds; a node that stops heartbeating is marked unavailable, and a node that shuts down cleanly says goodbye with a DISCONNECT packet so nobody waits for a timeout. When your code calls broker.call("greeter.hello", …), the caller's registry picks one live endpoint using a strategy and sends the request straight to that node. That is client-side discovery plus client-side load balancing, with the catalogue kept eventually consistent by gossip over the bus.

The setup

One service, deliberately trivial, that reports which node answered:

// services/greeter.service.js — the only service in this article.
// Every response says which node served it, so load balancing is visible.
module.exports = {
  name: "greeter",
  actions: {
    hello: {
      params: { name: "string" },
      handler(ctx) {
        return { hello: ctx.params.name, servedBy: this.broker.nodeID };
      },
    },
  },
};

One config, shared by every worker process and by the client. Everything the article varies is an environment variable; the service never changes:

// moleculer.config.js
const PreferZoneStrategy = require("./prefer-zone.strategy");   // custom strategy, shown later

// Built-in strategies are picked by name; a custom one is passed as a class.
const strategy = process.env.STRATEGY === "PreferZone" ? PreferZoneStrategy : process.env.STRATEGY || "RoundRobin";

module.exports = {
  nodeID: `worker-${process.pid}`,
  transporter: process.env.TRANSPORTER || "nats://localhost:4222",
  metadata: { zone: process.env.ZONE || "eu" }, // free-form node metadata, visible to every other node
  registry: {
    strategy,
    strategyOptions: { shardKey: "name" }, // only Shard reads this: route by ctx.params.name
    preferLocal: true,
  },
  heartbeatInterval: 2, // seconds; default 10
  heartbeatTimeout: 6,  // seconds; default 30 — shortened so the crash demo fits in a terminal
};

Workers are started with moleculer-runner, the framework's CLI host: SERVICEDIR=services npx moleculer-runner --config moleculer.config.js. The client is a broker with no services, which is a perfectly normal thing to be — an API gateway or a cron job looks exactly like this:

// client.js (abridged) — a node with no services of its own; it only calls greeter.hello.
const broker = new ServiceBroker({ ...config, nodeID: `client-${process.pid}` });
await broker.start();
await broker.waitForServices("greeter");            // block until at least one instance is known

for (const name of ["ada", "linus", "grace", "dennis", "ken", "brian"]) {
  const res = await broker.call("greeter.hello", { name });
  console.log(`${name.padEnd(7)} → ${res.servedBy}`);
}

1. Three workers, zero configuration

Start three workers and run the client:

$ node client.js calls 6
ada     → worker-3473401
linus   → worker-3473403
grace   → worker-3473402
dennis  → worker-3473401
ken     → worker-3473403
brian   → worker-3473402

Round-robin across three processes. Nobody registered anything anywhere; the workers announced themselves on the bus and the client's registry did the rest. You can ask any node what it currently knows — the registry is exposed as a built-in $node service:

const nodes = await broker.call("$node.list", { withServices: true });

$ node client.js nodes
client-3473436     available=true  zone=eu  services=-
worker-3473402     available=true  zone=eu  services=greeter
worker-3473401     available=true  zone=eu  services=greeter
worker-3473403     available=true  zone=eu  services=greeter

Note the zone=eu column: that's the metadata from the config, carried in the INFO packet. It will matter in a minute.

2. Scaling down, crashing, scaling up — with traffic running

This is the part registry vendors don't put in the quick-start. The client calls greeter.hello every 500 ms for 16 seconds. While it runs, I stop one worker cleanly (SIGTERM), kill another (SIGKILL, no goodbye), and start a new one.

$ node client.js loop 16
t=  0.0s  → worker-3473034
t=  0.5s  → worker-3473036
t=  1.0s  → worker-3473035
t=  1.5s  → worker-3473034          ← SIGTERM sent to worker-3473034 right after this
t=  2.1s  → worker-3473036
t=  2.6s  → worker-3473036
t=  3.1s  → worker-3473035
t=  3.6s  → worker-3473036
t=  4.1s  → worker-3473035
t=  4.6s  → worker-3473036
t=  5.1s  → worker-3473035
t=  5.6s  → worker-3473036          ← SIGKILL sent to worker-3473035 here
[20:45:57.784Z] WARN  BROKER: Request 'greeter.hello' is timed out. { nodeID: 'worker-3473035', timeout: 2000 }
t=  6.2s  ✗ RequestTimeoutError: Request is timed out when call 'greeter.hello' action on 'worker-3473035' node.
t=  8.7s  → worker-3473036
[20:46:00.807Z] WARN  BROKER: Request 'greeter.hello' is timed out. { nodeID: 'worker-3473035', timeout: 2000 }
t=  9.2s  ✗ RequestTimeoutError: Request is timed out when call 'greeter.hello' action on 'worker-3473035' node.
t= 11.7s  → worker-3473036
[20:46:01.618Z] WARN  DISCOVERY: Heartbeat is not received from 'worker-3473035' node.
[20:46:01.619Z] WARN  REGISTRY: Node 'worker-3473035' disconnected unexpectedly.
t= 12.2s  → worker-3473036
t= 12.7s  → worker-3473036
t= 13.3s  → worker-3473036
t= 13.8s  → worker-3473098          ← new worker, first request within a second of starting
t= 14.3s  → worker-3473036
t= 14.8s  → worker-3473098

Three different things happened, and it's worth being precise about each:

Graceful stop is instant. worker-3473034 got SIGTERM, the runner stopped the broker, the broker sent DISCONNECT, and the node was gone from every registry before the next call. Zero failed requests. This is what happens on every deploy, so it's the case that matters most.
A crash is detected by heartbeat, and until then calls to that node fail. worker-3473035 was killed at ~5.6 s. The registry only learned at ~11.6 s (heartbeatTimeout: 6), and in between, every request round-robined onto the dead node timed out. That's two failures out of eight calls. With the default heartbeatTimeout: 30 it would have been worse. No client-side registry can do better than its heartbeat window — Consul's agent has the same gap, Kubernetes' readiness probes have the same gap — the difference is only who notices and how you react. Reacting is what retries and circuit breakers are for; that's the next article. For now: tune heartbeatInterval/heartbeatTimeout to what your deployment can afford (2/6 is fine for a dozen nodes; the defaults are conservative for hundreds).
Scaling up is sub-second. worker-3473098 started, published INFO, and was serving traffic on the next tick. No registration step, no health-check grace period, no DNS TTL.

3. Choosing who gets the call: strategies

Round-robin is the default, but the strategy is a one-word option. Built in:

RoundRobin — the default; equal share, in order.
Random — equal share, no order; useful when many callers would otherwise stay in lockstep.
CpuUsage — samples the CPU load nodes report in their heartbeat, picks a lightly loaded one. Good for uneven hardware.
Latency — measures round-trip time to each node and prefers the fast ones. Good for multi-region.
Shard — consistent hashing on a field from the request, so the same key always lands on the same node. This is how you get in-memory per-user caches or ordered processing per key without a separate sticky-session layer.

Shard, keyed on name, same three workers:

$ STRATEGY=Shard node client.js calls 12
ada     → worker-3473403
linus   → worker-3473403
grace   → worker-3473471
dennis  → worker-3473471
ken     → worker-3473471
brian   → worker-3473471
ada     → worker-3473403
linus   → worker-3473403
grace   → worker-3473471
dennis  → worker-3473471
ken     → worker-3473471
brian   → worker-3473471

Same name, same node, every time — with a consistent-hash ring, so adding a node only moves the keys that land on it. Two things I learned while writing this: the key must be given as registry.strategyOptions.shardKey (I first tried strategy: { type: "Shard", options: {…} }, which is silently ignored and falls back to random selection — check the output, not the config), and the key can be read from ctx.meta instead of params with a # prefix ("#userId"), which is usually what you want since the user ID rides in meta. Strategies can also be set per action (strategy/strategyOptions on the action definition) if one hot action needs sharding and the rest don't.

Writing your own in fifteen lines

The strategy interface is one method: select(endpoints, ctx). Here's one that keeps traffic inside the caller's own zone when it can, and falls back to everything when it can't — the classic "same-AZ first" rule, without a mesh:

// prefer-zone.strategy.js — a custom load-balancing strategy in ~15 lines.
// Picks an instance in the caller's own zone when one is alive; falls back to any instance.
const { Strategies } = require("moleculer");

class PreferZoneStrategy extends Strategies.Base {
  constructor(registry, broker, opts) {
    super(registry, broker, opts);
    this.zone = broker.metadata.zone;
    this.fallback = new Strategies.RoundRobin(registry, broker, opts);
  }

  select(endpoints, ctx) {
    const local = endpoints.filter((ep) => ep.node.metadata?.zone === this.zone);
    return this.fallback.select(local.length ? local : endpoints, ctx);
  }
}

module.exports = PreferZoneStrategy;

Add a fourth worker with ZONE=us, then call from three different places:

$ node client.js nodes
worker-3473488     available=true  zone=us  services=greeter
worker-3473471     available=true  zone=eu  services=greeter
worker-3473403     available=true  zone=eu  services=greeter

$ STRATEGY=PreferZone ZONE=eu node client.js calls 6
ada     → worker-3473471
linus   → worker-3473403
grace   → worker-3473471
dennis  → worker-3473403
ken     → worker-3473471
brian   → worker-3473403

$ STRATEGY=PreferZone ZONE=us node client.js calls 6
ada     → worker-3473488
linus   → worker-3473488
grace   → worker-3473488
dennis  → worker-3473488
ken     → worker-3473488
brian   → worker-3473488

$ STRATEGY=PreferZone ZONE=asia node client.js calls 6      # no local instance → fall back to all
ada     → worker-3473403
linus   → worker-3473471
grace   → worker-3473488
dennis  → worker-3473403
ken     → worker-3473471
brian   → worker-3473488

The eu caller round-robins over the two eu workers, the us caller pins to its one us worker, and a caller from a zone with no workers uses all three. The metadata came from the registry — the strategy never made a network call. You can put anything in metadata: version, hardware class, canary flag, tenant — and route on it the same way.

One more rule you get for free: `preferLocal`

If the calling node itself hosts an instance of the service, preferLocal: true (the default) calls it in-process and skips the network entirely. That's what lets the same code run as a modular monolith on a laptop and as a distributed system in production — I showed that end-to-end in the previous article.

4. No message broker either: discovery over plain TCP

Everything above used NATS as the bus. If you don't want to run even that — a small deployment, an on-prem box, an edge device — Moleculer's TCP transporter has discovery built in: nodes find each other by UDP multicast and then talk over direct TCP connections. Same two workers, same client, one variable changed:

$ TRANSPORTER=TCP SERVICEDIR=services npx moleculer-runner --config moleculer.config.js
[20:47:29.966Z] INFO  TRANSPORTER: TCP server is listening on port 42799
[20:47:29.971Z] INFO  TRANSPORTER: UDP Multicast Server is listening on 192.168.1.20:4445. Membership: 239.0.0.0
[20:47:29.972Z] INFO  TRANSPORTER: UDP discovery started.

$ TRANSPORTER=TCP node client.js calls 4
ada     → worker-3473535
linus   → worker-3473536
grace   → worker-3473535
dennis  → worker-3473536

(IP address replaced; everything else is the actual log.) Service discovery and load balancing with no infrastructure process at all — not a registry, not a bus. The honest limitation: most cloud networks block multicast between VMs, so across hosts on AWS/GCP/Azure you either give the TCP transporter a static urls list of peers, or you use NATS/Redis, which is what I'd do anyway once there's more than one host.

When you still want Consul or Kubernetes

Being fair about the boundaries:

Polyglot systems. The registry lives in the Node.js processes. A Go or Python service can't join it (there are Java and Go ports that speak the same protocol, but they're separate community projects). If half your services aren't Node, an external registry is the lingua franca.
You're already on Kubernetes. Then keep it — for scheduling, restarts, secrets and ingress, it's excellent. It doesn't conflict: Kubernetes decides which pods exist, the broker's registry decides which action call goes to which pod and does so with application-level knowledge (versions, metadata, per-action strategies) that a Service object doesn't have. Many teams run exactly this combination, and it means the same code also runs on a plain VM.
Very large clusters. Every node hearing every heartbeat is O(n²) chatter. Past a few hundred nodes, switch the discoverer from the default gossip to the Redis- or etcd-backed one (registry.discoverer: "Redis") — heartbeats go to a shared store instead of the bus. That's one config line, and the rest of the article is unchanged.

For a Node.js system of, say, five to fifty services on a handful of machines — which is most systems — the registry in the framework covers service discovery, load balancing, zone affinity, sharding and node health, and the only infrastructure you ran for it in this article was one NATS container. Or, in the last demo, nothing.

Code in this article was run on Moleculer 0.15.2 and Node.js 22, with NATS 2 as the bus except in the TCP section. The moleculer-examples repository has a run.sh that reproduces all five demos, including the crash-and-recover timeline.

From a modular monolith to microservices without a rewrite

Icebob — Tue, 22 Sep 2026 13:00:14 +0000

Most "monolith to microservices" stories go one of two ways. Either it's a rewrite that takes eighteen months and ships a system nobody asked for, or it's a big-bang split into fifteen services that immediately need a Kubernetes team. Both come from the same mistake: treating "process boundaries" and "module boundaries" as the same decision.

They aren't. You can draw the module boundaries now, inside the monolith, and move the process boundaries later — one service at a time, when you have a reason to. This article shows exactly that with a small Express app: three stages, the same service files in every stage, and real output at each step, including the one thing that does break when you finally run two copies of a service.

The starting point

A perfectly ordinary Express monolith. Three modules, wired together with require(), one process.

// lib/orders.js — calls users and mailer through plain imports. Tight coupling, zero ceremony.
const users = require("./users");
const mailer = require("./mailer");

let counter = 0;
const orders = [];

exports.create = ({ userId, item, amount }) => {
  const user = users.get(userId);
  const order = { id: ++counter, userId, item, amount };
  orders.push(order);
  mailer.send(user.email, `Order #${order.id} confirmed (${item})`);
  return order;
};

// app.js
const express = require("express");
const users = require("./lib/users");
const orders = require("./lib/orders");

const app = express();
app.use(express.json());

app.get("/users/:id", (req, res) => res.json(users.get(Number(req.params.id))));
app.post("/orders", (req, res) => {
  const userId = Number(req.header("x-user-id"));
  res.status(201).json(orders.create({ userId, ...req.body }));
});

app.listen(process.env.PORT || 3000);

$ curl -s localhost:3000/users/1
{"id":1,"name":"Ada","email":"ada@example.com"}
$ curl -s -X POST localhost:3000/orders -H 'content-type: application/json' -H 'x-user-id: 2' -d '{"item":"Monitor","amount":329}'
{"id":1,"userId":2,"item":"Monitor","amount":329}

Nothing wrong with this. It's the right architecture for a team of three with one deployable. The problem only starts when orders grows a queue consumer, mailer needs to scale independently because a marketing campaign sends 200k emails, and you realise nothing in the codebase says which module is allowed to call which.

Stage 1: module boundaries become service boundaries — same process

Bring in a service broker (Moleculer's ServiceBroker — think of it as an in-process service runtime with a registry) and turn each module into a service: a plain object with a name and actions (its callable endpoints). No transporter is configured, so every call is an in-memory function call. No network, no serialization, no new infrastructure.

// services/orders.service.js — lib/orders.js as a service.
// No require("./users") any more: the dependency goes through the broker, and is declared.
let counter = 0;                       // module-level state — fine in a monolith; see "What breaks" below
const orders = [];

module.exports = {
  name: "orders",
  dependencies: ["users"],             // broker waits for `users` before starting this service
  actions: {
    create: {
      params: {
        userId: { type: "number", convert: true },
        item: "string",
        amount: { type: "number", positive: true },
      },
      async handler(ctx) {
        const user = await ctx.call("users.get", { id: ctx.params.userId });
        const order = { id: ++counter, userId: user.id, item: ctx.params.item, amount: ctx.params.amount };
        orders.push(order);
        await ctx.emit("order.created", { order, user });
        return { ...order, servedBy: this.broker.nodeID, usersServedBy: user.servedBy };
      },
    },
  },
};

Three things changed and they are all improvements you'd want anyway:

The dependency is explicit. dependencies: ["users"] is documentation the runtime enforces — orders won't start until users is available.
The input is validated at the boundary. params is a schema; a bad amount is rejected before the handler runs.
Mailer is no longer called — it's notified. orders emits order.created; whoever cares subscribes. That's the seam you'll use later to move it out.

// services/mailer.service.js — lib/mailer.js as a service. Instead of being called, it reacts to an event.
module.exports = {
  name: "mailer",
  events: {
    "order.created"(ctx) {
      const { order, user } = ctx.params;
      this.logger.info(`→ ${user.email}: Order #${order.id} confirmed (${order.item})`);
    },
  },
};

Express stays. The routes call the broker instead of the modules:

// app.js — the same Express app, now with a broker inside. Routes call services instead of modules.
const express = require("express");
const { ServiceBroker } = require("moleculer");

const broker = new ServiceBroker({
  nodeID: `app-${process.pid}`,
  transporter: process.env.TRANSPORTER || null,     // null = local bus, in-process only
  logger: { type: "Console", options: { level: "info", formatter: "short" } },
});

const wanted = process.env.SERVICES === undefined ? ["users", "orders", "mailer"] : process.env.SERVICES.split(",").filter(Boolean);
for (const name of wanted) broker.createService(require(`./services/${name}.service.js`));

const app = express();
app.use(express.json());

app.get("/users/:id", async (req, res, next) => {
  try { res.json(await broker.call("users.get", { id: req.params.id })); } catch (e) { next(e); }
});
app.post("/orders", async (req, res, next) => {
  try {
    const userId = Number(req.header("x-user-id"));
    res.status(201).json(await broker.call("orders.create", { userId, ...req.body }));
  } catch (e) { next(e); }
});
app.use((err, req, res, next) => res.status(err.code || 500).json({ error: err.name, message: err.message }));

broker.start().then(() => {
  app.listen(process.env.PORT || 3000, () => broker.logger.info(`HTTP on ${process.env.PORT || 3000}`));
});

$ node app.js
[20:06:31.508Z] INFO  BROKER: Node ID: app-3470689
[20:06:31.549Z] INFO  ORDERS: Waiting for service(s) 'users'...
[20:06:31.557Z] INFO  USERS: Service 'users' started.
[20:06:31.557Z] INFO  MAILER: Service 'mailer' started.
[20:06:32.552Z] INFO  ORDERS: Service(s) 'users' are available.
[20:06:32.554Z] INFO  ORDERS: Service 'orders' started.
[20:06:32.554Z] INFO  BROKER: ✔ ServiceBroker with 4 service(s) started successfully in 1s.
[20:06:32.557Z] INFO  BROKER: HTTP on 3000

$ curl -s localhost:3000/users/1
{"id":1,"name":"Ada","email":"ada@example.com","servedBy":"app-3470689"}
$ curl -s -X POST localhost:3000/orders -H 'content-type: application/json' -H 'x-user-id: 2' -d '{"item":"Monitor","amount":329}'
{"id":1,"userId":2,"item":"Monitor","amount":329,"servedBy":"app-3470689","usersServedBy":"app-3470689"}
# app log:
[20:06:34.088Z] INFO  MAILER: → linus@example.com: Order #1 confirmed (Monitor)

Same behaviour, same single process, same deploy. servedBy and usersServedBy are the same node because everything is local. You could stop here for a year and still be better off than before: the boundaries are real, the contracts are validated, and nobody can sneak a require("../orders/db") across modules any more.

This is what "modular monolith" should mean in practice — not a folder convention, but boundaries a runtime knows about.

Stage 2: extract one service — the one that actually needs it

Marketing week: mailer needs to scale on its own and must not slow down the request path. So move only mailer out.

Two changes, neither of them in service code. First, give the app a transporter (a message broker — NATS here) and tell it which services to host locally:

$ TRANSPORTER=nats://localhost:4222 SERVICES=users,orders node app.js

Second, start mailer in its own process with moleculer-runner, the framework's CLI service host, pointed at the same services/ folder:

// moleculer.config.js — for services that run OUTSIDE the app process, via moleculer-runner.
module.exports = {
  nodeID: `svc-${process.env.SERVICES || "all"}-${process.pid}`,
  transporter: process.env.TRANSPORTER || "nats://localhost:4222",
  logger: { type: "Console", options: { level: "info", formatter: "short" } },
};

$ SERVICEDIR=services SERVICES=mailer npx moleculer-runner --config moleculer.config.js

Now hit the same endpoints:

$ curl -s -X POST localhost:3000/orders -H 'content-type: application/json' -H 'x-user-id: 2' -d '{"item":"Monitor","amount":329}'
{"id":1,"userId":2,"item":"Monitor","amount":329,"servedBy":"app-3470296","usersServedBy":"app-3470296"}

# mailer process log:
[20:03:06.188Z] INFO  MAILER: → linus@example.com: Order #1 confirmed (Monitor)

Look at what happened:

mailer received the order.created event in another process, over NATS. The orders code that emits it didn't change.
orders → users is still app-3470296 → app-3470296: in-process. The app is connected to NATS, but the registry's default preferLocal: true routes a call to a local instance whenever one exists. You extracted one service and paid the network cost for exactly one hop — the one you chose.

That's the whole method. The services/ folder is the same in both processes; which process loads which file is a deployment decision, made per environment with two environment variables. Your dev laptop runs node app.js with everything local; staging runs the hybrid; production splits further. Same code.

Stage 3: split the rest, scale one — and meet the thing that breaks

Let's go all the way: users, orders and mailer each in their own process, two instances of orders because it's the hot path, and the app hosting nothing but HTTP:

$ SERVICEDIR=services SERVICES=users  npx moleculer-runner --config moleculer.config.js
$ SERVICEDIR=services SERVICES=orders npx moleculer-runner --config moleculer.config.js
$ SERVICEDIR=services SERVICES=orders npx moleculer-runner --config moleculer.config.js
$ SERVICEDIR=services SERVICES=mailer npx moleculer-runner --config moleculer.config.js
$ TRANSPORTER=nats://localhost:4222 SERVICES= node app.js

$ for i in 1 2 3 4; do curl -s -X POST localhost:3000/orders -H 'content-type: application/json' -H 'x-user-id: 1' -d '{"item":"Cable","amount":9}'; echo; done
{"id":1,"userId":1,"item":"Cable","amount":9,"servedBy":"svc-orders-3470323","usersServedBy":"svc-users-3470321"}
{"id":1,"userId":1,"item":"Cable","amount":9,"servedBy":"svc-orders-3470322","usersServedBy":"svc-users-3470321"}
{"id":2,"userId":1,"item":"Cable","amount":9,"servedBy":"svc-orders-3470323","usersServedBy":"svc-users-3470321"}
{"id":2,"userId":1,"item":"Cable","amount":9,"servedBy":"svc-orders-3470322","usersServedBy":"svc-users-3470321"}

The good news: round-robin load balancing between the two orders instances, calls to users over the wire, no code changes — all of it just works.

The bad news is in the first column. Order IDs 1, 1, 2, 2. Remember let counter = 0 at the top of orders.service.js? Each process has its own. In the monolith it was a perfectly good ID generator; with two instances it's a duplicate-key bug that would have shipped.

This is the honest part of the article. Turning modules into services is nearly free. Running two copies of one is where the monolith's hidden assumptions surface. Here is the list I check before scaling any service past one instance:

Module-level state — counters, caches, "the current batch", Maps of sessions. Every instance gets its own. Move it to the database or a shared store, or make it instance-safe (UUIDs instead of counters; here id: crypto.randomUUID() is the one-line fix).
In-memory cache. Moleculer's default Memory cacher is per node; with several instances you'll serve stale data from one and fresh from another. Switch the cacher to Redis — a broker option, not a code change.
Anything that assumes ordering across requests. Two instances process concurrently; if order mattered, you were relying on a single event loop.
Transactions across services. orders + inventory in one SQL transaction worked because they were one process on one connection. Across processes it's either a saga (compensating actions on failure) or you keep those two in the same service. Both are fine; pretending it's still atomic is not.
ctx.meta instead of globals. The request-scoped things you used to keep in req or a module variable (user ID, locale, trace ID) now need to ride along explicitly. Moleculer propagates ctx.meta through every call and event automatically — put them there.

None of these are Moleculer problems, and none of them are avoided by any other framework; they're the actual difference between one process and two. The point of the staged approach is that you hit them one service at a time, with a working system on both sides, instead of all at once on cut-over day.

The migration order that works

If I were doing this to a real codebase:

Stage 1 for everything, no exceptions. Broker in the monolith, every module a service, every cross-module call a ctx.call, every fire-and-forget a ctx.emit. Ship it. It is a refactor with no infrastructure change, and it's where you discover which modules actually depend on which.
Extract the asynchronous ones first. Mailer, image processing, report generation, webhooks — anything that already receives events rather than answering calls. They have no callers to break and their latency doesn't sit on the request path.
Extract what needs to scale or deploy independently. Usually one or two hot services. Run through the "what breaks" list before starting the second instance.
Leave the rest together. A modular monolith with two extracted services is a legitimate end state, not a half-finished migration. Every boundary you didn't turn into a network hop is one that can't fail at 3 a.m.

And keep node app.js — the everything-local mode — working forever. It's how a new developer runs the whole system on a laptop with no Docker, and it's how you run integration tests without a message broker. The local bus is a feature, not a stepping stone.

Code in this article was run on Moleculer 0.15.2, Express 5 and Node.js 22, with NATS 2 for stages 2 and 3. The moleculer-examples repository has a run.sh that reproduces all three stages — including the duplicate-ID bug — in one go.

Using Moleculer with TypeScript: contracts, two service styles, and the honest caveats

Icebob — Tue, 15 Sep 2026 13:00:42 +0000

"Does Moleculer work with TypeScript?" is the second most common question I get about it, right after the NestJS one. The short answer is yes — it ships its own type definitions, you can write services as typed schemas or as classes, and the runner loads .ts files. The longer answer has a few honest caveats, and since you'd hit them on day two anyway, I'd rather put them in the article.

This post shows a small typed system end to end: a shared contract file, two services in the two supported styles, a caller that gets autocomplete and compile errors for wrong action names, and the dev and production ways to run it. Everything below was compiled with strict: true and executed as shown, on Moleculer 0.15.2, Node.js 22 and TypeScript 7.

What Moleculer gives you out of the box

Bundled typings. moleculer ships index.d.ts; there is no @types/moleculer. The generics that matter: ServiceSchema<TSettings, TMethods, TVars> for typing this inside a service, Context<TParams, TMeta> for typing what a handler receives, and broker.call<TReturn, TParams>() for typing a call.
Class-based services. class X extends Service with this.parseServiceSchema({...}) in the constructor is a first-class way to define a service, not a hack.
.ts loading in the runner. moleculer-runner resolves moleculer.config.ts and *.service.ts files as long as a TypeScript loader is registered in the process (tsx, ts-node).
A TypeScript project template for the CLI (moleculer-cli → moleculer init project-typescript my-app), maintained alongside the framework.

What it does not give you — and I'll come back to each — is a decorator API in core, dependency injection, or any type information that crosses the network. That last one is not a Moleculer limitation, it is how distributed systems work, and the trick below is how you get most of the benefit anyway.

Step 1: a contract file

Action names are strings, and by default broker.call("products.get", { id: 1 }) returns Promise<any>. The fix is one file that says what each action takes and returns. Moleculer doesn't generate it; you write it, and both the service and every caller import it.

// src/contracts.ts — shared types for the actions in this system.
export interface Product { id: number; name: string; price: number; }
export interface Order { id: string; productId: number; quantity: number; total: number; }

/** Action name → { params, result }. */
export interface Actions {
  "products.get":  { params: { id: number };                       result: Product };
  "products.list": { params: { limit?: number };                   result: Product[] };
  "orders.create": { params: { productId: number; quantity: number }; result: Order };
}

/** Events and their payloads. */
export interface Events {
  "order.created": Order;
}

/** What every request carries in ctx.meta. */
export interface Meta { userId?: string; }

Then a ~25-line wrapper turns broker.call and ctx.emit into typed functions:

// src/typed-broker.ts
import type { Context, ServiceBroker, CallingOptions } from "moleculer";
import type { Actions, Events, Meta } from "./contracts";

export type ActionName = keyof Actions;
export type ActionParams<N extends ActionName> = Actions[N]["params"];
export type ActionResult<N extends ActionName> = Actions[N]["result"];

/** A Context whose params/meta are the ones declared for `N`. */
export type Ctx<N extends ActionName> = Context<ActionParams<N>, Meta>;
/** Same for event handlers: ctx.params is the event payload. */
export type EventCtx<E extends keyof Events> = Context<Events[E], Meta>;

export function call<N extends ActionName>(
  caller: ServiceBroker | Context<unknown, Meta>,
  action: N,
  params: ActionParams<N>,
  opts?: CallingOptions,
): Promise<ActionResult<N>> {
  return caller.call<ActionResult<N>, ActionParams<N>>(action, params, opts);
}

export function emit<E extends keyof Events>(ctx: Context<unknown, Meta>, event: E, payload: Events[E]) {
  return ctx.emit(event, payload);
}

This is the whole trick. Everything else in the article builds on it.

Step 2: a service in schema style

The schema object is Moleculer's native idiom. In TypeScript you annotate it as ServiceSchema<Settings, Methods>, and this.settings.currency and this.findOrFail() become type-checked inside handlers.

// services/products.service.ts
import type { ServiceSchema, Context } from "moleculer";
import type { Product, Meta } from "../src/contracts";

interface Settings { currency: string; }
interface Methods { findOrFail(id: number): Product; }

const catalogue: Product[] = [
  { id: 1, name: "Keyboard", price: 79 },
  { id: 2, name: "Monitor", price: 329 },
  { id: 3, name: "Cable", price: 9 },
];

const ProductsService: ServiceSchema<Settings, Methods> = {
  name: "products",
  settings: { currency: "EUR" },

  actions: {
    get: {
      // Runtime validation — the compiler cannot check what arrives over the wire.
      params: { id: { type: "number", convert: true } },
      handler(ctx: Context<{ id: number }, Meta>): Product {
        this.logger.info(`get #${ctx.params.id} for user ${ctx.meta.userId ?? "anonymous"}`);
        return this.findOrFail(ctx.params.id);          // typed via Methods
      },
    },
    list: {
      params: { limit: { type: "number", optional: true, convert: true } },
      handler(ctx: Context<{ limit?: number }, Meta>): Product[] {
        return catalogue.slice(0, ctx.params.limit ?? catalogue.length);
      },
    },
  },

  methods: {
    findOrFail(id) {
      const p = catalogue.find(p => p.id === id);
      if (!p) throw new Error(`Product ${id} not found`);
      return p;
    },
  },

  started() {
    this.logger.info(`products up, prices in ${this.settings.currency}`);   // typed via Settings
  },
};

export default ProductsService;

Two things to notice. The params block is runtime validation (Moleculer uses fastest-validator) and it stays there no matter how much TypeScript you add — the compiler has no idea what another process will send. And the Context<{ id: number }, Meta> annotation on the handler is what makes ctx.params.id a number rather than unknown; you could use the Ctx<"products.get"> alias from the wrapper instead, which is what the next service does.

Step 3: a service in class style

If your team thinks in classes, extend Service and pass the schema from the constructor. Handlers are plain methods, this is the class, and private state is a field.

// services/orders.service.ts
import { Service, ServiceBroker } from "moleculer";
import type { Order } from "../src/contracts";
import { call, emit, type Ctx, type EventCtx } from "../src/typed-broker";

export default class OrdersService extends Service {
  private orders: Order[] = [];

  constructor(broker: ServiceBroker) {
    super(broker);
    this.parseServiceSchema({
      name: "orders",
      actions: {
        create: {
          params: {
            productId: { type: "number", convert: true },
            quantity: { type: "number", min: 1, convert: true },
          },
          handler: this.create,
        },
      },
      events: {
        "order.created": this.onOrderCreated,
      },
    });
  }

  async create(ctx: Ctx<"orders.create">): Promise<Order> {
    // Typed call: the action name autocompletes, params are checked, the result is a Product.
    const product = await call(ctx, "products.get", { id: ctx.params.productId });

    const order: Order = {
      id: `ord_${this.orders.length + 1}`,
      productId: product.id,
      quantity: ctx.params.quantity,
      total: product.price * ctx.params.quantity,
    };
    this.orders.push(order);

    await emit(ctx, "order.created", order);   // payload must be an Order
    return order;
  }

  onOrderCreated(ctx: EventCtx<"order.created">) {
    this.logger.info(`event: order ${ctx.params.id} created, total ${ctx.params.total}`);
  }
}

Moleculer binds handlers to the service instance, so passing this.create as the handler is fine — inside it, this.orders and this.logger are what you expect.

Step 4: a typed caller

// src/client.ts
import { ServiceBroker } from "moleculer";
import { call } from "./typed-broker";

const broker = new ServiceBroker({
  nodeID: `client-${process.pid}`,
  transporter: { type: "NATS", options: { url: "nats://localhost:4222" } },
  logger: false,
});

async function main() {
  await broker.start();
  await broker.waitForServices(["products", "orders"]);

  const product = await call(broker, "products.get", { id: 2 });
  console.log("product:", product.name, product.price);        // product: Product

  const order = await call(broker, "orders.create", { productId: 2, quantity: 3 });
  console.log("order:", order.id, "total", order.total);       // order: Order

  // Runtime validation still guards the wire: force a bad payload past the compiler.
  try {
    await call(broker, "products.get", { id: "two" as unknown as number });
  } catch (err: any) {
    console.log("rejected:", err.name, "-", err.data?.[0]?.message);
  }

  await broker.stop();
}
main();

And here is what the compiler says when you get it wrong — this is the payoff of the contract file:

await call(broker, "products.get", { id: "2" });     // wrong param type
await call(broker, "product.get", { id: 2 });        // typo in the action name
const order = await call(broker, "orders.create", { productId: 2, quantity: 1 });
console.log(order.totl);                             // typo in a result field

$ npx tsc --noEmit -p .
src/mistakes.ts(8,40): error TS2322: Type 'string' is not assignable to type 'number'.
src/mistakes.ts(9,22): error TS2345: Argument of type '"product.get"' is not assignable to parameter of type 'keyof Actions'.
src/mistakes.ts(11,21): error TS2551: Property 'totl' does not exist on type 'Order'. Did you mean 'total'?

Three classes of bug that used to be runtime failures in another process are now red squiggles in the editor.

Step 5: running it

Development: run the .ts sources directly. moleculer-runner resolves .ts config and service files; it just needs a loader in the process, and tsx is the least fuss:

// moleculer.config.ts
import type { BrokerOptions } from "moleculer";

const config: BrokerOptions = {
  nodeID: `node-${process.pid}`,
  transporter: { type: "NATS", options: { url: process.env.TRANSPORTER ?? "nats://localhost:4222" } },
  logger: { type: "Console", options: { formatter: "short" } },
  requestTimeout: 2000,
};
export default config;

$ node --import tsx node_modules/.bin/moleculer-runner --config moleculer.config.ts --mask "**/*.service.ts" services
[17:49:58.859Z] INFO  PRODUCTS: products up, prices in EUR
[17:49:58.868Z] INFO  REGISTRY: 'orders' service is registered.
[17:49:58.869Z] INFO  REGISTRY: 'products' service is registered.
[17:49:58.870Z] INFO  BROKER: ✔ ServiceBroker with 3 service(s) started successfully in 869ms.

$ npx tsx src/client.ts
product: Monitor 329
order: ord_1 total 987
rejected: ValidationError - The 'id' field must be a number.

The --mask matters: the runner's default file mask is **/*.service.js, so without it your .ts services are silently skipped.

Production: compile once, ship JavaScript, run with plain Node. No loader in the hot path.

$ npx tsc -p .
$ node node_modules/.bin/moleculer-runner --config dist/moleculer.config.js dist/services
$ node dist/src/client.js
product: Monitor 329
order: ord_1 total 987
rejected: ValidationError - The 'id' field must be a number.

Same output, same services. In Docker this is a two-stage build: tsc in the first stage, only dist/ and production dependencies in the second.

The honest caveats

1. No decorators in core. If you want @Action() / @Event() on class methods, the community package moleculer-decorators does it. I tested version 1.3.0 against Moleculer 0.15.2 and it works:

import { ServiceBroker, Context, Service as MoleculerService } from "moleculer";
import { Service, Action, Event, Method } from "moleculer-decorators";

@Service({ name: "greeter", settings: { greeting: "Hello" } })
class GreeterService extends MoleculerService<{ greeting: string }> {
  @Action({ params: { name: "string" } })
  hello(ctx: Context<{ name: string }>) {
    return this.format(ctx.params.name);
  }

  @Method
  format(name: string) {
    return `${this.settings.greeting}, ${name}!`;
  }

  @Event()
  "user.signup"(ctx: Context<{ name: string }>) {
    this.logger.info(`welcome mail to ${ctx.params.name}`);
  }
}

$ npx tsx greeter.service.ts
Hello, Ada!

But be aware of what you're taking on: the package's last release was in 2022, it declares a dependency on Moleculer 0.14, and it uses the legacy experimentalDecorators flag rather than the standard (TC39) decorators that TypeScript 5+ supports. It is small and readable, so forking it is a realistic fallback — but it is not maintained by the core team, and I won't pretend otherwise. If decorators are a hard requirement for your team, weigh that.

2. Types don't cross the wire. The Actions interface is a promise you make to yourself. If the products service is deployed with a new field and the caller isn't, the compiler is happy and the runtime is what it is. Keep the contract file in a shared package (or a monorepo) and version it with the services. Runtime params validation stays mandatory — it is the only thing that checks what actually arrived.

3. Some option types are stricter than the runtime. Example you'll hit in the first five minutes: transporter: "nats://localhost:4222" is the documented shorthand and works at runtime, but BrokerOptions["transporter"] doesn't accept an arbitrary string, so under strict you'll get a type error. Use the object form { type: "NATS", options: { url } }, which is better anyway once you have more than one option. Expect a handful of these; the typings are hand-written and improve release by release (0.15 reworked them — this is typed in lifecycle handlers, for instance), and pull requests to them are the easiest way to contribute to the project.

4. No dependency injection. Moleculer has mixins for shared behaviour and this.broker for reaching other services, not a DI container. If your architecture leans on injectable providers and testing through container overrides, that's a real difference — see the NestJS comparison for when it matters.

5. this typing depends on you. Inside a schema, this is only as typed as the generics you pass to ServiceSchema. Skip them and this.settings.anything is any. It's a small discipline, but it is a discipline.

Recommendations

Start with the contract file + typed wrapper. It's the highest-value 50 lines in a Moleculer TypeScript project and it works with either service style.
Use schema style by default; it matches the docs and every example on the internet. Use class style when a service has enough private state and helpers that a class reads better.
Use Ctx<"action.name"> for handler signatures so the params type is defined once, in the contract, not repeated per handler.
tsx in development, tsc → dist/ in production. Don't ship a TypeScript loader to prod.
Keep strict: true and skipLibCheck: true — the second one saves you from type-checking your entire node_modules on every build.

If you already have a JavaScript Moleculer project, none of this requires a rewrite: rename a file to .ts, add the contract for the actions it calls, and go one service at a time.

Code in this article was compiled with TypeScript 7.0 (strict: true) and run on Moleculer 0.15.2, Node.js 22 and NATS 2. The full example, including a run.sh that exercises both the dev and the production path, is in the moleculer-examples repository.

Moleculer vs NestJS: which one, and when

Icebob — Mon, 07 Sep 2026 19:01:54 +0000

If you are choosing a framework for a Node.js backend that will be more than one service, you will end up comparing NestJS and Moleculer. People ask me about it constantly, usually phrased as "which is better?", and I maintain one of them, so you would expect a sales pitch.

You are not getting one. NestJS and Moleculer solve different problems and overlap in the middle, and the honest answer is that most teams should pick based on which problem they actually have. This article lays out the difference, shows the same service written in both, and ends with a decision list I would actually stand behind.

First, what each one is

NestJS is an application framework. It gives a Node.js codebase structure: modules, dependency injection, decorators, guards, pipes, interceptors, and a CLI that scaffolds all of it. It is TypeScript-first and Angular-shaped, and it has integrations for nearly everything — REST, GraphQL, WebSockets, Swagger, task scheduling, caching, queues. Its @nestjs/microservices package lets a Nest app listen on a message transport (TCP, Redis, NATS, MQTT, RabbitMQ, Kafka, gRPC) instead of HTTP, and call other apps over it.

Moleculer is a microservices framework. Its core concern is the distributed-systems layer: a service registry with discovery, load balancing between instances, request/response and pub/sub messaging over a pluggable transporter, and resilience — timeouts, retries, circuit breaker, bulkhead, fallbacks — built into every call. It also has caching, parameter validation, metrics and distributed tracing as broker options. It is less opinionated about how you structure the code inside a service: a service is a plain object with actions and event handlers.

The overlap is "several Node.js processes talking to each other over NATS". The difference is what each framework takes responsibility for once they do.

The same service, twice

Let's build the smallest realistic thing: a products service that runs as its own process, behind an HTTP gateway, with two instances for redundancy. Both versions use NATS. All of the code below runs as shown — Node 22, NestJS 12, Moleculer 0.15.

NestJS

The service is a controller with a message pattern, bootstrapped as a microservice. The queue option puts every instance in the same NATS queue group, which is what gives you load balancing.

// nest/products.service.ts — a NestJS "microservice": a NATS listener with message patterns.
import "reflect-metadata";
import { Controller, Module } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { MessagePattern, Payload, Transport, MicroserviceOptions } from "@nestjs/microservices";

@Controller()
class ProductsController {
  @MessagePattern("products.get")
  get(@Payload() data: { id: number }) {
    return { id: data.id, name: `Product #${data.id}`, price: 42, servedBy: `products-${process.pid}` };
  }
}

@Module({ controllers: [ProductsController] })
class ProductsModule {}

async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(ProductsModule, {
    transport: Transport.NATS,
    options: { servers: ["nats://localhost:4222"], queue: "products" }, // queue group = load balancing
  });
  await app.listen();
  console.log(`products microservice up (pid ${process.pid})`);
}
bootstrap();

The gateway is an ordinary Nest HTTP app with a ClientProxy injected. Note the two things you have to do yourself: convert the URL parameter with a pipe, and put a timeout on the call with RxJS.

// nest/gateway.ts — a NestJS HTTP app that calls the products microservice over NATS.
import "reflect-metadata";
import { Controller, Get, Module, Param, ParseIntPipe } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { ClientsModule, ClientProxy, Transport } from "@nestjs/microservices";
import { Inject } from "@nestjs/common";
import { firstValueFrom, timeout } from "rxjs";

@Controller("products")
class ProductsGatewayController {
  constructor(@Inject("PRODUCTS") private readonly client: ClientProxy) {}

  @Get(":id")
  get(@Param("id", ParseIntPipe) id: number) {
    // send() returns an Observable; you add timeouts/retries yourself.
    return firstValueFrom(this.client.send("products.get", { id }).pipe(timeout(2000)));
  }
}

@Module({
  imports: [
    ClientsModule.register([
      { name: "PRODUCTS", transport: Transport.NATS, options: { servers: ["nats://localhost:4222"] } },
    ]),
  ],
  controllers: [ProductsGatewayController],
})
class GatewayModule {}

async function bootstrap() {
  const app = await NestFactory.create(GatewayModule, { logger: ["error", "warn"] });
  await app.listen(process.env.PORT || 3000);
  console.log(`gateway on http://localhost:${process.env.PORT || 3000}`);
}
bootstrap();

Run two service instances and the gateway, then hit it:

$ npx tsx nest/products.service.ts &
$ npx tsx nest/products.service.ts &
$ npx tsx nest/gateway.ts &
$ for i in 1 2 3 4; do curl -s localhost:3000/products/$i; echo; done
{"id":1,"name":"Product #1","price":42,"servedBy":"products-3460437"}
{"id":2,"name":"Product #2","price":42,"servedBy":"products-3460417"}
{"id":3,"name":"Product #3","price":42,"servedBy":"products-3460437"}
{"id":4,"name":"Product #4","price":42,"servedBy":"products-3460437"}

$ curl -s localhost:3000/products/abc
{"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}

Load balancing works (NATS is doing it, not Nest — the queue group hands each message to one subscriber). Validation works because we added ParseIntPipe. Now stop both products processes and call again:

$ curl -s localhost:3000/products/5
{"statusCode":500,"message":"Internal server error"}
# gateway log: EmptyResponseException: Empty response. There are no subscribers listening to that message ("products.get")

Fast failure, which is good — NATS reports "no responders". But it is a generic 500, there is no retry, no circuit breaker, and nothing in the gateway knows that products exists at all except the string "products.get".

Moleculer

The same service as a Moleculer service schema. Validation is declared on the action; convert: true handles the string-from-URL case.

// moleculer/products.service.js — the same service in Moleculer.
const { ServiceBroker } = require("moleculer");

const broker = new ServiceBroker({
  nodeID: `products-${process.pid}`,
  transporter: "nats://localhost:4222",
  logger: false,
});

broker.createService({
  name: "products",
  actions: {
    get: {
      params: { id: { type: "number", convert: true } },   // validation is part of the action
      handler(ctx) {
        return { id: ctx.params.id, name: `Product #${ctx.params.id}`, price: 42, servedBy: this.broker.nodeID };
      },
    },
  },
});

broker.start().then(() => console.log(`products service up (${broker.nodeID})`));

The gateway uses moleculer-web, which is a service that maps HTTP routes to actions. The timeout is a broker option, so it applies to every call in the process.

// moleculer/gateway.js — HTTP edge, mapping a route to the action.
const { ServiceBroker } = require("moleculer");
const ApiGateway = require("moleculer-web");

const broker = new ServiceBroker({
  nodeID: `gateway-${process.pid}`,
  transporter: "nats://localhost:4222",
  logger: false,
  requestTimeout: 2000,                       // global; NestJS needs rxjs timeout() per call
});

broker.createService({
  name: "api",
  mixins: [ApiGateway],
  settings: {
    port: process.env.PORT || 3000,
    routes: [{ path: "/", aliases: { "GET /products/:id": "products.get" } }],
  },
});

broker.start().then(() => console.log(`gateway on http://localhost:${process.env.PORT || 3000}`));

$ node moleculer/products.service.js &
$ node moleculer/products.service.js &
$ node moleculer/gateway.js &
$ for i in 1 2 3 4; do curl -s localhost:3000/products/$i; echo; done
{"id":1,"name":"Product #1","price":42,"servedBy":"products-3460597"}
{"id":2,"name":"Product #2","price":42,"servedBy":"products-3460596"}
{"id":3,"name":"Product #3","price":42,"servedBy":"products-3460597"}
{"id":4,"name":"Product #4","price":42,"servedBy":"products-3460596"}

$ curl -s localhost:3000/products/abc
{"name":"ValidationError","message":"Parameters validation error!","code":422,"type":"VALIDATION_ERROR","data":[{"type":"number","message":"The 'id' field must be a number.","field":"id","actual":"abc","nodeID":"gateway-3460598","action":"products.get"}]}

# stop both products processes, then:
$ curl -s localhost:3000/products/5
{"name":"ServiceNotAvailableError","message":"Service 'products.get' is not available.","code":404,"type":"SERVICE_NOT_AVAILABLE","data":{"action":"products.get"}}

Here the load balancing is done by Moleculer's registry (round-robin by default; you can switch to latency-based, CPU-based or sharded). When the service instances went away, the gateway knew — it has a live registry of every node and action in the cluster, updated by heartbeats — and returned a structured, typed error. Add retryPolicy and circuitBreaker to the broker options and you get retries and a breaker on every call with no code changes; the previous article shows both in action.

What you would have to add to NestJS

If you build a multi-service system on @nestjs/microservices, here is what is not in the box and what people typically bolt on:

Service registry / discovery — nothing. You rely on the broker's semantics (NATS subjects, Kafka topics) or on Kubernetes DNS. There is no way to ask "which services are online, on which nodes?"
Load balancing — only what the transport gives you (NATS queue groups, Kafka consumer groups). TCP transport: one address, no balancing.
Retries, circuit breaker, bulkhead, fallback — nothing built in. opossum, RxJS retry(), or a service mesh.
Timeouts — per call, with RxJS timeout().
Payload validation on the message side — ValidationPipe with class-validator DTOs, same as HTTP.
Caching of RPC results — @nestjs/cache-manager on the HTTP side; nothing at the transport level.
Metrics & tracing across service calls — community OpenTelemetry packages; you propagate context yourself.
Local vs remote transparency — a ClientProxy always goes through the broker, even to a handler in the same process. There is no "start as a monolith, split later" mode.

None of this is a criticism. NestJS's microservices package is a transport abstraction — it makes a Nest app able to talk over a broker with the same controller idioms as HTTP. That is exactly what it claims to be. It is just not a service layer, and the difference matters a lot once you have ten services and a bad Tuesday.

What you would have to add to Moleculer

The other direction is just as real:

TypeScript ergonomics. Moleculer ships type definitions and works fine in TypeScript, but its native idiom is the schema object, not decorators and classes. Community packages (moleculer-decorators, TypeScript project templates) close some of the gap; the DX is not at NestJS's level, and I'd rather say that than have you find out later. The 0.15 release invested in typings (typed service lifecycle handlers, middleware, error handlers), and it keeps improving.
Dependency injection. Moleculer has mixins and service-level this for shared logic, not a DI container. If your team's mental model is Angular-style providers, you will miss it.
Application structure. Nest's CLI scaffolds modules, tests and DTOs and enforces a layout. Moleculer has a project generator, but inside a service you organise the code however you like.
Ecosystem breadth. NestJS has an official module for nearly every integration. Moleculer has an API gateway, database adapters, channels (queue-based reliable events), Socket.IO, GraphQL — and then you're writing your own service around an npm client, which is easy but is yours to maintain.
Community size and hiring. This is the honest big one. NestJS has ~76k GitHub stars and ~54 million monthly npm downloads; Moleculer has ~6k stars and ~250k downloads. A NestJS job ad gets more applicants who have used it. If you are building a team of twenty, that difference is worth real money.

Can you use both?

Yes, and it is more common than you'd think. The combinations that work:

Moleculer as the internal service layer, NestJS at the edge. Nest handles HTTP with its full toolkit (guards, Swagger, GraphQL), and a Moleculer broker running inside the Nest process calls the services. You get Nest's DX where users touch the system and Moleculer's registry, balancing and resilience behind it.
NestJS everywhere, Moleculer for one hairy subsystem that needs pub/sub with balanced consumers, sharding or circuit breaking that you don't want to hand-roll.

What doesn't work well is running both frameworks' microservices transports side by side for the same calls — pick one owner for inter-service communication.

Which one, and when

Pick NestJS if:

You are building one service, or a monolith that might split someday. Most apps are this. Nest is the better single-app framework, full stop.
Your team is TypeScript-native and values decorators, DI and enforced structure.
You need the breadth: GraphQL federation, WebSocket gateways, Swagger generation, Passport strategies, all official.
Hiring and onboarding speed matter more than the distributed-systems layer.
You already run Kubernetes with a service mesh, so discovery and resilience are the platform's job.

Pick Moleculer if:

You are building a system of many services now, and you do not want to assemble discovery, balancing, retries, circuit breakers, caching and tracing from six separate packages.
You do not have Kubernetes or a service mesh and don't want to run one — Moleculer gives you those properties on a VM with Docker Compose (see Node.js microservices without Kubernetes).
Your architecture is event-driven — balanced and broadcast events across services, over NATS, Redis, Kafka or MQTT, are first-class.
You want to start as a modular monolith and split into processes later without changing service code.
Plain JavaScript is fine, or you're happy with Moleculer's level of TypeScript support.

And if you're undecided: build the first service in NestJS. If the day comes when you have five of them calling each other and you find yourself writing a retry helper for the third time, that's the moment to look at Moleculer — and the boundary between the two is clean enough that you can.

Code in this article was run against NestJS 12.0 and Moleculer 0.15.2 on Node.js 22 with NATS 2. The full example project, including scripts that reproduce the outputs above, is in the moleculer-examples repository.

Node.js microservices without Kubernetes (and without a platform team)

Icebob — Mon, 07 Sep 2026 18:50:32 +0000

Somewhere around 2018 the phrase "we're doing microservices" silently became "we're running Kubernetes". The two ideas fused. Today when a Node.js team asks how to split a backend into services, the answer they get is a shopping list: a cluster, an ingress controller, a service mesh for retries and mTLS, Consul or CoreDNS for discovery, Prometheus and Jaeger wired into sidecars, and a Helm chart per service to hold it all together.

That stack is excellent. It is also, for most teams that are not Google, the wrong first step. This article is about the other path: getting the actual properties of microservices — independent deployment, service discovery, load balancing, fault isolation, an event bus — in plain Node.js processes, on a single VM or a handful of them, without an orchestrator.

I maintain Moleculer, a microservices framework for Node.js and TypeScript that was built for exactly this, so the examples use it. But the argument comes first, and it holds regardless of which tool you pick.

What you actually need from "microservices"

Strip away the branding and a microservice architecture is a short list of capabilities:

Service discovery — service A needs to find a live instance of service B without hardcoding IPs.
Load balancing — if B has three instances, calls should spread across them, and a dead instance should stop receiving traffic.
Inter-service communication — request/response (RPC) and publish/subscribe (events), with serialization handled for you.
Resilience — timeouts, retries, circuit breakers, bulkheads and fallbacks so one slow dependency doesn't take the whole system down.
Observability — metrics and distributed tracing across service boundaries.
Independent deployment — ship service B without redeploying A.

Kubernetes plus a service mesh gives you all of that at the infrastructure level: discovery via DNS and Services, balancing via kube-proxy or Envoy, resilience via Istio/Linkerd policies, tracing via sidecars. It is a legitimate design. It's just a lot of moving parts, and every one of them is something your team has to run, upgrade and debug at 3am.

The alternative is to put those capabilities in the application layer — in a library your services import — and let the infrastructure be as dumb as a VM with Docker Compose. That's the Moleculer model.

Moleculer in sixty seconds

A few terms, each glossed with what you'd type into a search box:

ServiceBroker — the runtime and service registry that lives in every process. It knows which services exist, where they are, and routes calls to them.
Service — a named object with actions (RPC endpoints, callable as "orders.create") and event handlers (subscribers).
Transporter — the message broker / transport layer between processes: NATS, Redis, Kafka, MQTT, AMQP or plain TCP. Swappable with one config line.

The crucial property: a service's code does not know whether the service it's calling is in the same process or on another machine. ctx.call("products.get") is the same line either way.

Step 1: three services, one process

Let's write a tiny shop: products, orders and notifications. Here is the business logic, and note that this file never changes for the rest of the article.

// services.js — the business logic. It never changes between "one process" and "many processes".

const Products = {
  name: "products",
  actions: {
    get: {
      params: { id: { type: "number", convert: true } }, // convert: URL params arrive as strings
      handler(ctx) {
        return { id: ctx.params.id, name: `Product #${ctx.params.id}`, price: 42, servedBy: this.broker.nodeID };
      },
    },
  },
};

const Orders = {
  name: "orders",
  actions: {
    create: {
      params: { productId: "number", qty: "number" },
      async handler(ctx) {
        // Looks like a local function call — may be a network hop. The framework decides.
        const product = await ctx.call("products.get", { id: ctx.params.productId });
        const order = { id: Date.now(), product, qty: ctx.params.qty, total: product.price * ctx.params.qty };
        // Publish an event. Whoever cares subscribes.
        await ctx.emit("order.created", order);
        return order;
      },
    },
  },
};

const Notifications = {
  name: "notifications",
  events: {
    "order.created"(ctx) {
      this.logger.info(`Email sent: order ${ctx.params.id}, total ${ctx.params.total} (from ${ctx.nodeID})`);
    },
  },
};

module.exports = { Products, Orders, Notifications };

The params block is a validation schema (Moleculer ships with fastest-validator); an invalid call is rejected with a structured ValidationError before your handler runs.

Now load all three into a single broker and run it. No message broker, no Docker, nothing listening on a port:

// monolith.js — all three services in ONE process. No broker, no network, no Docker.
const { ServiceBroker } = require("moleculer");
const { Products, Orders, Notifications } = require("./services");

const broker = new ServiceBroker({ logger: { type: "Console", options: { level: "info" } } });

broker.createService(Products);
broker.createService(Orders);
broker.createService(Notifications);

broker.start()
  .then(() => broker.call("orders.create", { productId: 7, qty: 3 }))
  .then((order) => console.log("Order:", order))
  .then(() => broker.stop());

$ npm install moleculer
$ node monolith.js
INFO  dev-laptop-51203/NOTIFICATIONS: Email sent: order 1788453205755, total 126 (from dev-laptop-51203)
Order: {
  id: 1788453205755,
  product: { id: 7, name: 'Product #7', price: 42, servedBy: 'dev-laptop-51203' },
  qty: 3,
  total: 126
}

This is a modular monolith: one deployable, but the modules only talk through the same contract they'd use over a network. It is a perfectly good place to stay for a long time. Many Moleculer users never leave it.

Step 2: split into processes with one config line

To run the services in separate processes, add a transporter. We'll use NATS — a single ~20 MB binary with no dependencies, and the best default for most teams.

$ docker run -d -p 4222:4222 nats:2
$ npm install nats

The node script takes the names of the services it should host from the command line:

// node.js — start ONE process that hosts the services named on the command line.
//   node node.js products
//   node node.js orders notifications
// Same service code as before. The only new thing is the transporter.
const { ServiceBroker } = require("moleculer");
const all = require("./services");

const broker = new ServiceBroker({
  nodeID: `${process.argv.slice(2).join("+")}-${process.pid}`,
  transporter: process.env.TRANSPORTER || "nats://localhost:4222",
  logger: { type: "Console", options: { level: "info" } },
});

for (const name of process.argv.slice(2)) {
  const schema = Object.values(all).find((s) => s.name === name);
  if (!schema) throw new Error(`Unknown service: ${name}`);
  broker.createService(schema);
}

broker.start();

Start two of them in two terminals:

$ node node.js products
$ node node.js orders notifications

And a client that has no services of its own — it just joins the cluster and calls in:

// client.js — a broker with no services of its own; it just calls into the cluster.
const { ServiceBroker } = require("moleculer");

const broker = new ServiceBroker({
  nodeID: "client",
  transporter: process.env.TRANSPORTER || "nats://localhost:4222",
  logger: false,
});

broker.start()
  .then(() => broker.waitForServices(["orders"]))
  .then(async () => {
    for (let i = 1; i <= 4; i++) {
      const order = await broker.call("orders.create", { productId: i, qty: 2 });
      console.log(`order ${order.id} → total ${order.total}, product served by ${order.product.servedBy}`);
    }
    // Built-in introspection: which nodes are online and what do they host?
    const nodes = await broker.call("$node.list", { withServices: true });
    for (const n of nodes) console.log(`node ${n.id}: ${n.services.map((s) => s.name).filter((s) => s !== "$node").join(", ")}`);
  })
  .then(() => broker.stop());

$ node client.js
order 1788453251083 → total 84, product served by products-3455407
order 1788453251095 → total 84, product served by products-3455407
order 1788453251104 → total 84, product served by products-3455407
order 1788453251112 → total 84, product served by products-3455407
node client:
node orders+notifications-3455409: orders, notifications
node products-3455407: products

Look at what just happened without any configuration:

The orders process called products.get in a different process. Nobody told it where products lives.
The order.created event crossed the network and reached notifications (check the second terminal — it logged the four emails).
The client discovered the whole cluster via the built-in $node service — a service registry you get for free.

That is service discovery. There is no Consul, no etcd, no DNS trick. When a node starts it announces itself over the transporter; every other broker updates its local registry; heartbeats detect when a node disappears. The registry lives inside each process, so a lookup is a hash-map read, not a network call.

Step 3: scale a service by starting another copy

Open a third terminal and start a second products process. Then run the client again:

$ node node.js products      # second instance
$ node client.js
order 1788453267932 → total 84, product served by products-3455456
order 1788453267948 → total 84, product served by products-3455458
order 1788453267956 → total 84, product served by products-3455456
order 1788453267965 → total 84, product served by products-3455458
node orders+notifications-3455460: orders, notifications
node products-3455456: products
node products-3455458: products

Calls now alternate between the two instances. That's the default round-robin load balancing; you can switch to random, CPU-usage-based, latency-based or shard-by-key strategies with one option. Stop one of the products processes and traffic moves to the survivor: a graceful stop deregisters the node immediately, and a hard crash is caught by the heartbeat timeout (configurable; the balancing docs cover the strategies and the fault-tolerance docs the failover behaviour).

Notice the shape of the "deploy": starting a process. Scaling: starting another process. There is no Deployment manifest, no replica count to reconcile, no rollout to watch. If your team runs services with systemd, PM2 or Docker Compose, you already have everything the framework needs.

Resilience is a broker option, not a library

In the Kubernetes world, retries, timeouts and circuit breaking usually arrive with the service mesh. Without a mesh you'd reach for opossum, p-retry and AbortSignal.timeout and glue them into every call site. Moleculer bakes them into the call path:

// resilience.js — timeout, retry and circuit breaker are broker options, not extra libraries.
const { ServiceBroker, Errors } = require("moleculer");

const broker = new ServiceBroker({
  logger: false,
  requestTimeout: 500,                    // ms; a hanging call becomes a RequestTimeoutError
  retryPolicy: { enabled: true, retries: 2, delay: 50, factor: 2 },
  circuitBreaker: {
    enabled: true,
    threshold: 0.5,                       // open when >50% of calls fail...
    minRequestCount: 5,                   // ...after at least 5 calls
    windowTime: 60,                       // seconds
    halfOpenTime: 5_000,                  // ms until we probe again
  },
});

let calls = 0;
broker.createService({
  name: "payments",
  actions: {
    charge: {
      retryPolicy: { enabled: false },     // retries make no sense for a non-idempotent charge
      handler() {
        calls++;
        throw new Errors.MoleculerError("gateway down", 503); // 5xx errors count against the breaker
      },
    },
    fallbackDemo: {
      fallback: () => ({ cached: true }),  // return this instead of throwing
      handler() { throw new Errors.MoleculerError("nope", 500); },
    },
  },
});

broker.start().then(async () => {
  for (let i = 1; i <= 8; i++) {
    try { await broker.call("payments.charge", { amount: 10 }); }
    catch (err) { console.log(`call ${i}: ${err.name} (${err.message})`); }
  }
  console.log("handler actually ran:", calls, "times");
  console.log("fallback:", await broker.call("payments.fallbackDemo"));
  await broker.stop();
});

$ node resilience.js
call 1: MoleculerError (gateway down)
call 2: MoleculerError (gateway down)
call 3: MoleculerError (gateway down)
call 4: MoleculerError (gateway down)
call 5: MoleculerError (gateway down)
call 6: ServiceNotAvailableError (Service 'payments.charge' is not available.)
call 7: ServiceNotAvailableError (Service 'payments.charge' is not available.)
call 8: ServiceNotAvailableError (Service 'payments.charge' is not available.)
handler actually ran: 5 times
fallback: { cached: true }

After five failures the circuit breaker opened and the next calls failed fast without touching the handler — exactly what you want when a payment gateway is melting down. Retries and timeouts are configured globally and overridden per action (note retryPolicy: { enabled: false } on the non-idempotent charge). A bulkhead (per-action concurrency limit) is one more option. None of this needed a sidecar.

Putting an HTTP door on it

Services talk to each other over the transporter, but browsers speak HTTP. The moleculer-web package is an API gateway that is itself a service — it joins the cluster like any other node and maps routes to actions:

// gateway.js — HTTP edge. It is just another node in the cluster; it owns no business logic.
const { ServiceBroker } = require("moleculer");
const ApiGateway = require("moleculer-web");

const broker = new ServiceBroker({
  nodeID: `gateway-${process.pid}`,
  transporter: process.env.TRANSPORTER || "nats://localhost:4222",
  logger: { type: "Console", options: { level: "warn" } },
});

broker.createService({
  name: "api",
  mixins: [ApiGateway],
  settings: {
    port: process.env.PORT || 3000,
    routes: [{
      path: "/api",
      // Only expose what you list here; everything else stays internal to the cluster.
      whitelist: ["products.get", "orders.create"],
      aliases: {
        "GET /products/:id": "products.get",
        "POST /orders": "orders.create",
      },
      bodyParsers: { json: true },
    }],
  },
});

broker.start().then(() => console.log(`Gateway listening on http://localhost:${process.env.PORT || 3000}/api`));

$ npm install moleculer-web
$ node gateway.js
$ curl localhost:3000/api/products/7
{"id":7,"name":"Product #7","price":42,"servedBy":"products-3455667"}

$ curl -X POST localhost:3000/api/orders -H 'content-type: application/json' -d '{"productId":7,"qty":2}'
{"id":1788453318747,"product":{"id":7,"name":"Product #7","price":42,"servedBy":"products-3455612"},"qty":2,"total":84}

$ curl -X POST localhost:3000/api/orders -H 'content-type: application/json' -d '{"productId":"x"}'
{"name":"ValidationError","message":"Parameters validation error!","code":422,"type":"VALIDATION_ERROR","data":[{"type":"number","message":"The 'productId' field must be a number.","field":"productId","actual":"x","nodeID":"gateway-3455616","action":"orders.create"},{"type":"required","message":"The 'qty' field is required.","field":"qty","nodeID":"gateway-3455616","action":"orders.create"}]}

The gateway has no knowledge of where products runs. The validation error came from the schema on the service, propagated back through the transporter, and was turned into a 422 automatically. Run two gateways behind nginx or Caddy and you've got a redundant edge.

Deploying without an orchestrator

Here is the entire production topology for a small team, as a Compose file. One VM (or one per service if you like), a NATS container, and your Node processes:

# docker-compose.yml — the whole "cluster" on one VM. No orchestrator.
services:
  nats:
    image: nats:2

  products:
    build: .
    command: node node.js products
    environment: { TRANSPORTER: nats://nats:4222 }
    depends_on: [nats]
    deploy: { replicas: 2 }          # two instances; the framework balances between them

  orders:
    build: .
    command: node node.js orders notifications
    environment: { TRANSPORTER: nats://nats:4222 }
    depends_on: [nats]

  gateway:
    build: .
    command: node gateway.js
    environment: { TRANSPORTER: nats://nats:4222 }
    ports: ["3000:3000"]
    depends_on: [nats]

docker compose up -d and you have a load-balanced, self-discovering, fault-tolerant service cluster. To spread it over several machines, point every TRANSPORTER at the same NATS host — NATS itself clusters trivially if you need it to be redundant. Metrics (Prometheus, StatsD, Datadog) and distributed tracing (Jaeger, Zipkin, OpenTelemetry) are broker options too, so observability doesn't need sidecars either.

What you give up compared to Kubernetes, honestly:

Automatic rescheduling. If a VM dies, nothing restarts your containers elsewhere. You handle it with a second VM and a health check, or accept the risk.
Rolling deploys as a primitive. Compose replaces containers; for zero-downtime you rely on Moleculer's graceful shutdown (a stopping node deregisters first and, with request tracking enabled, waits for in-flight requests before exiting) plus at least two replicas.
Autoscaling. You scale by editing replicas. For most teams that's a feature.
Secrets, RBAC, network policy. You use your OS and cloud provider's tools instead.

When you do want Kubernetes

If you already run a cluster, keep it — Moleculer runs perfectly well inside pods. The two layers are complementary rather than competing: Kubernetes handles scheduling, restarts and rollouts; Moleculer handles discovery, balancing and resilience at the application level, which means you don't need a service mesh on top. The official Kubernetes guide covers it.

You should also reach for an orchestrator when you have a genuinely large fleet (dozens of services, hundreds of instances), strict multi-tenant isolation requirements, or a platform team whose job it is to run one.

But if you are three developers with a product to ship, the honest answer to "how do we do microservices in Node.js?" is: one message broker, a framework that owns the distributed-systems layer, and processes you start with a command you already know. Start as a modular monolith, split when a boundary is real, scale by launching another copy. Get to Kubernetes when Kubernetes solves a problem you actually have.

All the code above runs as shown against Moleculer 0.15 on Node.js 22. The full example project is at github.com/moleculerjs/moleculer-examples — docs at moleculer.services.