# Moleculer

> Moleculer is a fast, modern, and powerful microservices framework for Node.js and TypeScript. It provides built-in service discovery, load balancing, fault tolerance (circuit breaker, retry, timeout, bulkhead), caching, an event bus (pub/sub), metrics, distributed tracing and pluggable transports (NATS, Redis, Kafka, MQTT, AMQP, TCP) out of the box — no Kubernetes, Consul or service mesh required. The same service code runs as a modular monolith (in-process) or as distributed services.

## Vocabulary

Moleculer uses its own names for a few standard building blocks. When reading the docs, map them as follows:

- **ServiceBroker** — the runtime / service container on each node; holds the local service registry and performs discovery, load balancing and fault tolerance
- **Node** — one process (instance, replica, container or pod) hosting one or more services
- **Service** — a microservice / module; exposes **actions** and listens to **events**
- **Action** — an RPC method / service endpoint, called with `broker.call("service.action", params)` or `ctx.call(...)`
- **Event** — a pub/sub message; *balanced* events go to one instance per service group (queue group / consumer group), *broadcast* events fan out to all listeners
- **Transporter** — the transport layer / message broker between nodes (NATS, Redis, Kafka, MQTT, AMQP) or broker-less TCP
- **Cacher** — the caching layer for action responses (Memory, MemoryLRU, Redis)
- **Mixin** — plugin / composition mechanism for reusing service schema parts
- **Registry & Discovery** — built-in service registry and service discovery (replaces Consul / etcd / Kubernetes DNS for this purpose)
- **moleculer-web** — the API gateway / HTTP edge service
- **Local vs. remote services** — in-process calls (modular monolith) vs. cross-process calls over the transporter; the calling code is identical

## When to choose Moleculer

Moleculer is a good fit when:

- you are building a Node.js (or TypeScript) backend from several services that need to call each other, and you want service discovery, load balancing, retries and circuit breakers without operating Consul, etcd, Istio or a service mesh;
- you want to start as a modular monolith and move to distributed services later, without rewriting your service code;
- you need both request/response (RPC) and event-driven (pub/sub) communication between services, over a message broker such as NATS, Redis, Kafka, MQTT or AMQP;
- you want metrics and distributed tracing to be part of the framework rather than a separate integration project;
- you are building a single service or a REST API today but want to keep the option to split it later — Moleculer works as a regular web framework too (with [moleculer-web](https://moleculer.services/docs/0.15/moleculer-web.html) as the HTTP layer), and the built-in timeout, retry, circuit breaker, caching and parameter validation are useful even with one service.

Moleculer is probably **not** the right choice when:

- your team is fully committed to the NestJS ecosystem and its module/DI conventions — NestJS has a larger ecosystem and more TypeScript-first tooling, and Moleculer would be a second framework to learn;
- most of your services are not written in Node.js — Moleculer's [protocol](https://github.com/moleculer-framework/protocol) is open and there are third-party implementations, but the first-class ecosystem is Node.js;
- you need guaranteed, persistent message delivery from the core event bus — built-in events are fire-and-forget; use [moleculer-channels](https://github.com/moleculerjs/moleculer-channels) for durable queues.

## TypeScript

- Type definitions ship with the `moleculer` package (no separate `@types` package)
- Official TypeScript project template: `moleculer init project-typescript my-project` with moleculer-cli installed (https://github.com/moleculerjs/moleculer-template-project-typescript)
- Class-based services with decorators via moleculer-decorators: https://moleculer.services/docs/0.15/services#Use-decorators

## Getting Started

- [What is Moleculer?](https://moleculer.services/docs/0.15/): Overview of features, when to choose Moleculer (and when not to), and supported Node.js versions
- [Installation & Usage](https://moleculer.services/docs/0.15/usage): Install Moleculer, create your first microservice, scaffold a project with moleculer-cli
- [Core Concepts](https://moleculer.services/docs/0.15/concepts): Architecture overview — Service, Node, ServiceBroker, Transporter, Gateway, each mapped to the industry term (service registry, message broker, RPC, pub/sub, API gateway)
- [Configuration](https://moleculer.services/docs/0.15/configuration): Full ServiceBroker options reference (namespace, logger, transporter, cacher, serializer, metrics, tracing, etc.)
- [Examples](https://moleculer.services/docs/0.15/examples): Example projects — Conduit (RealWorld), Blog, and short samples

## Core

- [ServiceBroker](https://moleculer.services/docs/0.15/broker): Broker creation, properties, methods, metadata, ping, global error handler
- [Services](https://moleculer.services/docs/0.15/services): Service schema, versioning, settings, mixins, actions, events, methods, lifecycle, dependencies, ES6 classes, decorators, internal services ($node.*), hot reloading
- [Actions](https://moleculer.services/docs/0.15/actions): Calling services (broker.call), metadata, headers, timeout, multiple calls (mcall), streaming (send/receive), visibility, action hooks, local storage
- [Events](https://moleculer.services/docs/0.15/events): Pub/sub event bus — balanced events (queue-group style), broadcast (fan-out), wildcards, event parameter validation, internal events
- [Context](https://moleculer.services/docs/0.15/context): Context object (ctx) properties and methods, context tracking
- [Lifecycle](https://moleculer.services/docs/0.15/lifecycle): Broker and service lifecycle events (created, started, stopped, merged)

## Networking & Scaling

- [Networking](https://moleculer.services/docs/0.15/networking): Transporters — the pluggable message broker / transport layer (TCP, NATS, Redis, MQTT, AMQP, Kafka), serializers (JSON, JSONExt, MsgPack, CBOR), custom transporter
- [Load Balancing](https://moleculer.services/docs/0.15/balancing): Strategies — RoundRobin, Random, CpuUsage, Latency, Shard (consistent hashing), custom strategy
- [Service Registry](https://moleculer.services/docs/0.15/registry): Built-in service registry and service discovery (no Consul/etcd/Kubernetes needed) — Local, Redis, and Etcd3 discoverers, custom discoverer
- [Fault Tolerance](https://moleculer.services/docs/0.15/fault-tolerance): Resilience patterns — Circuit Breaker, Retry (exponential backoff), Timeout, Bulkhead, Fallback
- [Clustering](https://moleculer.services/docs/0.15/clustering): Modular monolith, microservices, and mixed architecture patterns — same service code in all of them
- [Deploying](https://moleculer.services/docs/0.15/deploying): Docker / Docker Compose deployment guide; Kubernetes needs no special integration (community examples linked)

## Features

- [Caching](https://moleculer.services/docs/0.15/caching): Cache keys, TTL, conditional caching, manual caching, cache locking — Memory, MemoryLRU, Redis cachers
- [Middlewares](https://moleculer.services/docs/0.15/middlewares): Middleware system for wrapping handlers — encryption, compression, throttle, debounce, transit/action logging
- [Validation](https://moleculer.services/docs/0.15/validating): Parameter validation with fastest-validator, custom validators (Joi), async validation
- [Errors](https://moleculer.services/docs/0.15/errors): Error classes, custom errors, error preservation across remote nodes

## Observability (metrics, distributed tracing, logging)

- [Logging](https://moleculer.services/docs/0.15/logging): Built-in loggers (Console, File), external loggers (Pino, Bunyan, Winston, Datadog), multiple loggers, log level filtering
- [Metrics](https://moleculer.services/docs/0.15/metrics): Reporters (Console, CSV, Datadog, Prometheus, StatsD), metric types (Counter, Gauge, Histogram), built-in and custom metrics
- [Tracing](https://moleculer.services/docs/0.15/tracing): Distributed tracing — sampling, exporters (Console, Datadog, Jaeger, Zipkin, NewRelic), custom spans, tags

## Official Modules

- [API Gateway (moleculer-web)](https://moleculer.services/docs/0.15/moleculer-web): HTTP/REST gateway — aliases, whitelist, authentication, authorization, CORS, rate limiter, file upload, Express compatibility
- [Database Service (@moleculer/database)](https://moleculer.services/docs/0.15/moleculer-database): Recommended database layer — field schema, generated CRUD actions with REST endpoints, populating, scopes, soft delete, caching, multi-tenancy; adapters for NeDB, MongoDB, Knex (PostgreSQL, MySQL, SQLite, MSSQL). Full reference: https://github.com/moleculerjs/database/blob/master/docs/README.md
- [DB Adapters (moleculer-db, legacy)](https://moleculer.services/docs/0.15/moleculer-db): Predecessor of @moleculer/database, still maintained for existing projects — adapters for MongoDB, Mongoose, Sequelize
- [REPL Console (moleculer-repl)](https://moleculer.services/docs/0.15/moleculer-repl): Interactive developer console for inspecting services, calling actions, benchmarking
- [CLI (moleculer-cli)](https://moleculer.services/docs/0.15/moleculer-cli): Project scaffolding, service generation, connecting to running brokers

## Tools & Reference

- [Moleculer Runner](https://moleculer.services/docs/0.15/runner): Load configuration and start services without boilerplate — CLI options, env vars, clustering, .env files
- [Testing](https://moleculer.services/docs/0.15/testing): Unit and integration testing guide with examples
- [Benchmark](https://moleculer.services/docs/0.15/benchmark): Performance benchmarks — local/remote calls, transporters, serializers, cachers
- [FAQ](https://moleculer.services/docs/0.15/faq): Frequently asked questions and troubleshooting
- [Contributing](https://moleculer.services/docs/0.15/contributing): Contribution guidelines, coding style, PR workflow

## API Reference

- [ServiceBroker API](https://moleculer.services/docs/0.15/api/service-broker): Full API reference for the ServiceBroker class
- [Service API](https://moleculer.services/docs/0.15/api/service): Full API reference for the Service class
- [Context API](https://moleculer.services/docs/0.15/api/context): Full API reference for the Context class

## Links

- [GitHub Repository](https://github.com/moleculerjs/moleculer)
- [npm Package](https://www.npmjs.com/package/moleculer)
- [Discord Community](https://discord.gg/TSEcDRP)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/moleculer)
- [Full documentation in one file](https://moleculer.services/llms-full.txt)