Required dependencies

npm install args eventemitter2 fastest-validator glob ipaddr.js kleur lodash lru-cache recursive-watch

No native build steps, pod installs, or prebuild commands are required. All dependencies are pure JavaScript.

Project setup

1. Copy the source/ directory into your project, for example at lib/moleculer/.
2. (TypeScript) Add a path alias in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "moleculer/*": ["lib/moleculer/*"]
    }
  }
}

3. Reference the broker entry point directly:

import ServiceBroker = require("./lib/moleculer/service-broker");

4. No required environment variables for basic usage. Optional env vars used by specific adapters:
   • REDIS_URL - used by Redis cacher/transporter if you pass it as a connection string
   • DATADOG_API_KEY - needed only if using Datadog logger or metrics reporter
5. For ESM projects using the runner, use runner-esm.mjs as the entry point.

Public API

Cachers.resolve

function resolve(
  opt: Record<string, any> | string | boolean | null
): BaseCacher | null;

Resolves and instantiates a cacher from a string name ("Memory", "Redis", a redis:// URL), a config object { type, options }, or true for the default in-memory cacher. Returns null if opt is falsy. Use this when wiring broker options or writing middleware that needs caching without hardcoding a cacher class.

Loggers.resolve

function resolve(
  opt: Record<string, any> | string
): BaseLogger;

Resolves and instantiates a logger by string name ("Console", "Winston", etc.) or config object { type, options }. Throws BrokerOptionsError on unknown type. Use this to build a logger pipeline before constructing the broker, or to swap loggers in tests.

Reporters.resolve (metrics)

function resolve(
  opt: Record<string, any> | string
): BaseReporter;

Resolves a metrics reporter by name ("Prometheus", "StatsD", "Console", etc.) or config object. Throws BrokerOptionsError on unknown type. Use this when configuring the MetricRegistry with a custom reporter list.

Cachers.register / Reporters.register

function register(name: string, value: any): void;

Adds a custom cacher or reporter class under a given name so it can later be resolved by that name string. Use this to extend the framework with third-party adapters without modifying source files.

Working examples

Scenario - Minimal service broker with in-memory caching

Create a broker with the default Memory cacher, define a math service, and call an action.

const ServiceBroker = require("./lib/moleculer/service-broker");

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

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

broker.start()
  .then(() => broker.call("math.add", { a: 5, b: 3 }))
  .then((result: number) => console.log("Result:", result))
  .then(() => broker.stop());

Scenario - Custom cacher via Cachers.resolve

Resolve a Redis cacher from a connection string and pass it directly to the broker.

const ServiceBroker = require("./lib/moleculer/service-broker");
const { resolve: resolveCacher } = require("./lib/moleculer/cachers");

const cacher = resolveCacher("redis://localhost:6379");

const broker = new ServiceBroker({ cacher });

broker.createService({
  name: "cache-demo",
  actions: {
    async get(ctx: any) {
      const cached = await this.broker.cacher.get(ctx.params.key);
      if (cached) return cached;
      const value = { computed: true, key: ctx.params.key };
      await this.broker.cacher.set(ctx.params.key, value, 60);
      return value;
    }
  }
});

broker.start()
  .then(() => broker.call("cache-demo.get", { key: "hello" }))
  .then((v: any) => console.log(v))
  .then(() => broker.stop());

Scenario - Prometheus metrics reporter

Wire a Prometheus reporter into the broker so metrics are exposed at /metrics.

const ServiceBroker = require("./lib/moleculer/service-broker");
const { resolve: resolveReporter } = require("./lib/moleculer/metrics/reporters");

const reporter = resolveReporter({ type: "Prometheus", options: { port: 3030 } });

const broker = new ServiceBroker({
  metrics: {
    enabled: true,
    reporter: [reporter]
  }
});

broker.createService({ name: "ping", actions: { ping: () => "pong" } });

broker.start().then(() => {
  console.log("Prometheus metrics available at http://localhost:3030/metrics");
});

Scenario - Register a custom logger and resolve it

const { register, resolve } = require("./lib/moleculer/loggers");
const BaseLogger = require("./lib/moleculer/loggers/base");

class MyLogger extends BaseLogger {
  getLogHandler(bindings: any) {
    return (type: string, args: any[]) => console.log(`[MY] [${type}]`, ...args);
  }
}

register("MyLogger", MyLogger);

const logger = resolve({ type: "MyLogger", options: {} });
console.log(logger instanceof BaseLogger); // true

File walkthrough

• service-broker.js - Top-level broker class; all services, middleware, and subsystems attach here.
• service.js - Defines the Service class that broker.createService() instantiates.
• context.js - Encapsulates a single call/event invocation with params, metadata, and span.
• errors.js - Exports all named error classes (BrokerOptionsError, ServiceNotFoundError, etc.).
• transit.js - Handles serialization and dispatch of packets between nodes.
• packets.js - Packet schema definitions used by transit.
• middleware.js - Runs the ordered middleware chain for every broker operation.
• logger-factory.js - Constructs and binds logger instances to broker/service namespaces.
• constants.js - Shared string constants used across the framework.
• utils.js - isObject, isString, isInheritedClass, and other internal helpers.
• health.js - Gathers node health data for $node.health built-in action.
• lock.js - Lightweight async mutex used internally by cachers.
• runner.js / runner-esm.mjs - CLI entry points for moleculer-runner invocation.
• internals.js - Registers $node.* internal services on the broker.
• async-storage.js - AsyncLocalStorage wrapper for context propagation without explicit passing.
• cpu-usage.js - Periodic CPU sampling used by the cpu-usage load-balancing strategy.
• cachers/ - Base + Memory + MemoryLRU + Redis implementations with factory resolver.
• loggers/ - Base + eight concrete logger adapters with factory resolver.
• metrics/ - MetricRegistry, four metric types, seven reporter adapters, METRIC constants.
• middlewares/ - Built-in middleware hooks (circuit-breaker, bulkhead, retry, timeout, etc.).
• registry/ - Node/service/action/event catalog and endpoint lists.
• serializers/ - Pluggable serialization layer between transit peers.
• strategies/ - Endpoint selection strategies for load balancing.
• tracing/ - Distributed tracing context and exporter adapters.
• transporters/ - Network transport adapters for inter-node communication.
• validators/ - Parameter validation hook wrapping fastest-validator.

Common pitfalls and fixes

• lru-cache API mismatch - lru-cache v7+ changed its API; pin "lru-cache": "^6.0.0" in your package.json to match v0.15.0 expectations.
• Redis cacher peer dep - ioredis is not in dependencies; install it separately with npm install ioredis before using the Redis cacher or transporter.
• ESM / CJS interop - All source files use require(); if your project is "type": "module", use createRequire or import via the .mjs runner; do not rename files.
• fastest-validator version - The validator adapter expects the v1.x API; npm install fastest-validator@^1 explicitly to avoid v2 breaking changes.
• Transporter peer deps not bundled - NATS, Kafka, MQTT, and AMQP adapters each require their own client library (nats, kafkajs, mqtt, amqplib); install only the ones you use.
• TypeScript strict mode - The .d.ts files use implicit any in several places; add "skipLibCheck": true in tsconfig.json to prevent type errors from source declarations.

Vibe-coding prompt template

I have the Moleculer microservices framework source copied into `lib/moleculer/`
in my Node.js/TypeScript project. I also have the file `USAGE.md` in my project
root which documents the real exports, file layout, and working examples for this
source (upstream package: user@example.com).

Please help me integrate it step by step:

1. Read `USAGE.md` and `lib/moleculer/service-broker.js` to understand the broker API.
2. Create a `src/broker.ts` that instantiates a ServiceBroker with a Console logger
   and Memory cacher, using only real exports shown in `USAGE.md`.
3. Create a sample service in `src/services/example.service.ts` with at least two actions.
4. Wire broker start/stop into my existing Express app lifecycle (show where to call
   broker.start() relative to app.listen()).
5. Show how to add a Prometheus metrics reporter using `lib/moleculer/metrics/reporters`
   resolve() function exactly as documented in `USAGE.md`.
6. Point out any missing peer dependencies I need to install based on the adapters I am using.

Do not invent any API methods. Use only symbols visible in `USAGE.md` and the source files.

License and credit

Moleculer is released under the MIT License. See source/LICENSE if present, or refer to the official repository. Upstream package: moleculer on npm, maintained by MoleculerJS.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.