Moleculer Runner is a helper script that helps you run Moleculer projects. With it, you don’t need to create a ServiceBroker instance with options. Instead, you can create a
moleculer.config.js file in the root of repo with broker options. Then simply call the
moleculer-runner in NPM script, and it will automatically load the configuration file, create the broker and load the services. Alternatively, you can declare your configuration as environment variables.
moleculer.config.jsduring development or store common options. In production, you can overwrite the values with the environment variables!
$ moleculer-runner [options] [service files or directories or glob masks]
Note: It runs in this format in NPM scripts only. To call it directly from your console, use the
node ./node_modules/moleculer/bin/moleculer-runner.js --replformat.
||If true, it switches to REPL mode after broker started.|
||Disable the broker logger. It prints nothing to the console.|
||Hot reload services when they change.|
||Load configuration file from a different path or a different filename.|
||Load environment variables from the ‘.env’ file from the current folder.|
||Load environment variables from the specified file.|
||Launch [number] node instances or
Example NPM scripts
dev script loads development configurations from the
moleculer.dev.config.js file, start all services from the
services folder, enable hot-reloading and switches to REPL mode. Run it with the
npm run dev command.
start script is to load the default
moleculer.config.js file if it exists, otherwise only loads options from environment variables. Starts 4 instances of broker, then they start all services from the
services folder. Run it with
npm start command.
The runner does the following steps to load & merge configurations:
- Load the config file defined in
MOLECULER_CONFIGenvironment variable. If it does not exist, it throws an error.
- It loads config file defined in CLI options. If it does not exist, it throws an error. Note that
MOLECULER_CONFIGhas priority over CLI meaning that if both are defined
MOLECULER_CONFIGis the one that’s going to be used.
- If not defined, it loads the
moleculer.config.jsfile from the current directory. If it does not exist, it loads the
- Once a config file has been loaded, it merges options with the default options of the ServiceBroker.
- The runner observes the options step by step and tries to overwrite them from environment variables. Once
logLevel: "warn"is set in the config file, but the
LOGLEVEL=debugenvironment variable is defined, the runner overwrites it, and it results:
To overwrite broker’s deeply nested default options, which are not present in
moleculer.config.js, via environment variables, use the
MOL_prefix and double underscore
__for nested properties in
.envfile. For example, to set the cacher prefix to
MOLyou should declare as
The structure of the configuration file is the same as that of the broker options. Every property has the same name.
Example config file
Moleculer Runner also supports asynchronous configuration files. In this case
moleculer.config.js must export a
Function that returns a
Promise (or you can use
This function runs with the
MoleculerRunnerinstance as the
thiscontext. Useful if you need to access the flags passed to the runner. Check the MoleculerRunner source more details.
The runner transforms the property names to uppercase. If nested, the runner concatenates names with
Example environment variables
The runner loads service files or folders defined in CLI arguments. If you define folder(s), the runner loads all services
**/*.service.js from specified one(s) (including sub-folders too). Services & service folder can be loaded with
SERVICEDIR environment variables.
SERVICEDIRenv found, but no
SERVICESenv, it loads all services from the
SERVICESenv found, it loads the specified services from the
- If no
SERVICESenv found, it loads the specified services from the current directory.
- Check the CLI arguments. If filename found, it loads them. If directory found, it loads them. If glob pattern found, it applies and load the found files.
Please note: shorthand names can also be used in
It loads the
user.service.js files from the
It loads all
*.service.js files from the
my-services folder (including sub-folders too).
If you want to be more specific, use glob patterns. It is useful when loading all services except certain ones.
$ moleculer-runner services !services/others/**/*.service.js services/others/mandatory/main.service.js
services- legacy mode. Load all services from the
!services/others/**/*.service.js- skip all services in the
services/othersfolder and sub-folders.
services/others/mandatory/main.service.js- load the exact service.
The glob patterns work in the
SERVICESenvironment variables, as well.
Moleculer Runner has a built-in clustering function to start multiple instances from your broker.
Example to start all services from the
services folder in 4 instances.
$ moleculer-runner --instances 4 services
Clustered Node ID
nodeIDwill be suffixed with the worker ID. E.g. if you define
my-nodenodeID in options, and starts 4 instances, the instance nodeIDs will be
Moleculer runner can load
.env file at starting. There are two new cli options to load env file:
-e, --env- Load environment variables from the ‘.env’ file from the current folder.
-E, --envfile <filename>- Load environment variables from the specified file.
# Load the default .env file from current directory
To use this feature, install the
npm install dotenv --savecommand.