{"id":11352,"library":"moleculer","title":"Moleculer Microservices Framework","description":"Moleculer is a fast, modern, and powerful microservices framework for Node.js, designed to build efficient, reliable, and scalable distributed systems. It provides a comprehensive set of features including a promise-based request-reply mechanism, event-driven architecture, dynamic service discovery, load balancing, and fault tolerance capabilities like Circuit Breaker and Retry. The current stable version is 0.15.0, with frequent minor and patch releases, and major updates approximately annually, often introducing significant breaking changes. Key differentiators include its pluggable architecture for transporters (e.g., NATS, Redis, Kafka), serializers (e.g., MsgPack, CBOR), caching, loggers, and metrics/tracing reporters. It emphasizes a master-less architecture, making all nodes equal, and comes with built-in parameter validation and extensive TypeScript support.","status":"active","version":"0.15.0","language":"javascript","source_language":"en","source_url":"https://github.com/moleculerjs/moleculer","tags":["javascript","microservice","microservices","framework","backend","messagebus","rpc","services","micro","typescript"],"install":[{"cmd":"npm install moleculer","lang":"bash","label":"npm"},{"cmd":"yarn add moleculer","lang":"bash","label":"yarn"},{"cmd":"pnpm add moleculer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required if using AMQP 0.9.1 as a transporter for message brokering.","package":"amqplib","optional":true},{"reason":"Required if using NATS as a transporter for high-performance messaging.","package":"nats","optional":true},{"reason":"Used for Redis-based transporters, caching, and distributed locking (via redlock).","package":"ioredis","optional":true},{"reason":"One of several pluggable loggers supported by Moleculer.","package":"pino","optional":true},{"reason":"One of several pluggable loggers supported by Moleculer.","package":"bunyan","optional":true},{"reason":"One of several pluggable loggers supported by Moleculer.","package":"winston","optional":true},{"reason":"An optional high-performance serializer for message encoding.","package":"cbor-x","optional":true}],"imports":[{"note":"Moleculer v0.15 is primarily ESM-first. While CommonJS might still work in some setups, the recommended approach is ESM. `ServiceBroker` is the core class for creating and managing a broker instance.","wrong":"const { ServiceBroker } = require('moleculer');","symbol":"ServiceBroker","correct":"import { ServiceBroker } from 'moleculer';"},{"note":"The base class for defining services. Always imported as a named export from the main 'moleculer' package. For TypeScript, it's also the base class for type inference.","wrong":"import Service from 'moleculer/service';","symbol":"Service","correct":"import { Service } from 'moleculer';"},{"note":"The primary interface for defining service configurations and actions. It's a type, but also implicitly inferred when defining service objects.","wrong":"import { ServiceSchema } from 'moleculer/types';","symbol":"ServiceSchema","correct":"import { ServiceSchema } from 'moleculer';"},{"note":"Transporters namespace provides access to various built-in transporters like `Nats`, `Redis`, `Kafka`, etc. Generally accessed as `new Transporters.Nats(...)`.","wrong":"import { NatsTransporter } from 'moleculer/transporters/nats';","symbol":"Transporters","correct":"import { Transporters } from 'moleculer';"}],"quickstart":{"code":"import { ServiceBroker, ServiceSchema } from 'moleculer';\n\n// Create a ServiceBroker\nconst broker = new ServiceBroker({\n  nodeID: 'node-greeter-1',\n  logLevel: 'info',\n  transporter: 'NATS' // Or 'Redis', 'TCP', etc.\n});\n\n// Define a Greeter Service\nconst GreeterService: ServiceSchema = {\n  name: 'greeter',\n  settings: {\n    defaultName: 'World'\n  },\n  actions: {\n    hello: {\n      rest: 'GET /hello',\n      async handler(ctx) {\n        return `Hello ${ctx.params.name || this.settings.defaultName}`;\n      }\n    },\n    welcome: {\n      async handler(ctx) {\n        this.logger.info(`Welcoming ${ctx.params.name}...`);\n        return `Welcome, ${ctx.params.name}`;\n      }\n    }\n  },\n  events: {\n    'user.created': {\n      async handler(ctx) {\n        this.logger.info(`User created event received for ${ctx.params.username}`);\n      }\n    }\n  },\n  async started() {\n    this.logger.info(`Greeter service started on node ${broker.nodeID}`);\n  },\n  async stopped() {\n    this.logger.info(`Greeter service stopped on node ${broker.nodeID}`);\n  }\n};\n\n// Create a service from the schema\nbroker.createService(GreeterService);\n\n// Start the broker\nbroker.start()\n  .then(async () => {\n    // Call an action\n    const res = await broker.call('greeter.hello', { name: 'Moleculer' });\n    console.log(res);\n\n    // Emit an event\n    await broker.emit('user.created', { username: 'Alice' });\n\n    // Call an action from another node if available (assuming multiple nodes)\n    const welcomeMsg = await broker.call('greeter.welcome', { name: 'Bob' });\n    console.log(welcomeMsg);\n\n    // Stop the broker after a delay or on signal\n    setTimeout(() => broker.stop(), 5000);\n  })\n  .catch(err => {\n    broker.logger.error('Error starting broker:', err);\n  });\n","lang":"typescript","description":"This quickstart demonstrates how to create a basic Moleculer service, define actions and events, start the service broker, and then call an action and emit an event."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 22 or newer. Ensure your deployment environment meets this requirement.","message":"Moleculer v0.15.0 significantly increased the minimum Node.js version requirement. It now requires Node.js >= 22.x.x.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"All nodes in your Moleculer cluster must be upgraded to v0.15.0 simultaneously to maintain communication. Consider a phased rollout with caution, or a complete upgrade of the entire microservices mesh.","message":"The Moleculer communication protocol has been changed in v0.15.0 to version 5. Nodes running v0.15.x will not be able to communicate with nodes running v0.14.x or older due to protocol incompatibility.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"Review your serialization strategy. Moleculer still supports pluggable serializers like JSON, JSONExt, MsgPack, CBOR, and Notepack. Migrate to one of these or implement a custom serializer as a plugin.","message":"Schema-based serializers were removed from the core in v0.15.0. If you were relying on custom schema-based serializers, they need to be reimplemented or replaced with other serialization options.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"Always install the required peer dependency for any specific transporter, logger, or other module you configure. For example, if using `transporter: 'NATS'`, you must `npm install nats`.","message":"Moleculer relies heavily on various peer dependencies for its pluggable components (transporters, loggers, serializers, metrics, tracing). Forgetting to install the specific peer dependency for a chosen component will lead to runtime errors.","severity":"gotcha","affected_versions":">=0.10.0"},{"fix":"Verify `\"target\": \"es2017\"` (or higher) and `\"moduleResolution\": \"node\"` or `\"nodenext\"` in your `tsconfig.json`. Consider adding `\"lib\": [\"es2017\", \"esnext.asynciterable\"]` for full type coverage.","message":"When developing with TypeScript, ensure your `tsconfig.json` targets an ECMAScript version that supports `async/await` (e.g., `es2017` or higher) and includes `esnext.asynciterable` if using streams, and that `moduleResolution` is set to `node` or `nodenext`.","severity":"gotcha","affected_versions":">=0.14.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the required package. For example, if using NATS, run `npm install nats` (or `yarn add nats`).","cause":"You configured a transporter (e.g., 'NATS', 'Redis') in your `ServiceBroker` options but did not install its corresponding npm package.","error":"Error: Missing transporter module."},{"fix":"Ensure `broker.start()` has successfully resolved before making any calls or emits. Wrap your logic within the `.then()` block of `broker.start()` or ensure a running broker instance.","cause":"Attempting to call actions or emit events on the `ServiceBroker` instance before it has been started or after it has been stopped.","error":"TypeError: broker.call is not a function or broker.emit is not a function"},{"fix":"Verify the service name and action name are correct. Ensure the service is created with `broker.createService()` and the broker is started, allowing it to discover services across the network.","cause":"You are trying to call an action on a service that hasn't been created, registered, or is not available in the network.","error":"Service not found"}],"ecosystem":"npm"}