= erun

Multi-environment aware task runner for NodeJs projects.

image:https://nodei.co/npm/erun.png["NodeJs public registry listing",link="https://github.com/bguiz/erun/"]

image:https://travis-ci.org/bguiz/erun.svg?branch=develop["Continuous Integration Build Status",link="https://travis-ci.org/bguiz/erun"]

== Installation

[source,bash]

npm install --save-dev erun

== Usage

Run the following on the command line.

[source,bash]

Runs myTask with NODE_ENV=localhost

npm run erun -- myTask localhost

Runs myTask with NODE_ENV=dev and with 2 extra arguments

npm run erun -- myTask dev argOne argTwo

Runs myTask with NODE_ENV=production and NODE_SUB_ENV=staging

npm run erun -- myTask production-staging

Specify envSplitOn in erunConfig if you wish to make use of NODE_SUB_ENV. This is optional, but useful when you need to support multiple deployment environments which utilise the same NODE_ENV, e.g. production might have live, staging, pentest, and loadtest.

== Configuration

Edit package.json.

For convenience, create an npm run script first:

[source,json]

{ "scripts": { "erun": "erun " } }

Next add an erun hash, containing one or more erun scripts.

Each one needs a cmd as a string, and optionally may specify env as a hash of environment variables.

=== cmd

[source,json]

{ "erun": { "start": { "cmd": "node ./server/run.js" }, "start localhost": { "cmd": "nodemon --inspect ./server/run.js", "env": { "DEBUG": "true" } } } }

In the above example, npm run erun -- start localhost would be the equivalent of executing DEBUG=true nodemon --inspect ./server/run.js, whereas npm run erun -- start dev (or any environment other than localhost) would be the equivalent of executing node ./server/run.js

=== env

Optionally, also edit package.json to add erunConfig.

[source,json]

{ "erunConfig": { "envSplitOn": "-" } }

=== Variable substitution

You can use the ${something} syntax to substitute environment variables within the env hash, as well as the cmd string.

[source,json]

{ "erun": { "test": { "cmd": "mocha --reporter mochawesome ./test/${NODE_ENV}-bootstrap.js ./test/**/*.spec.js", "env": { "MOCHAWESOME_REPORTDIR": "./reports/test/${NODE_ENV}", "MOCHAWESOME_REPORTTITLE": "Tests on ${NODE_ENV}" } } } }

In the above example, we see this employed in a test task, where NODE_ENV is used within the env hash to differ the report file name and title, and used within cmd to differ the "bootstrap" file loaded prior to the "spec" files.

=== Differing behaviour per environment

==== Differing cmd:

You can specify a default erun command for all environments, and also one for some environments or even sub-environments.

[source, json]

{ "erun": { "start": { "cmd": "node ./server/start.js" }, "start localhost": { "cmd": "nodemon --inspect ./server/start.js" } } }

In the above example, erun start dev or erun start production would run the server script via node, but only erun start localhost would run the server script via nodemon.

==== Differing env:

If you would like the cmd to be the same on a particular environment, but have different environment variables, you can do that too.

[source, json]

{ "erun": { "start": { "cmd": "node ./server/start.js" }, "start localhost": { "env": { "DEBUG": "true" } } } }

In the above example, erun start localhost, erun start dev, and erun start production would all run the server script via node, but only erun start localhost would do so with the DEBUG environment variable set.

==== Differing both cmd and env

Should you wish to do this, simply set both cmd and env, as shown above, and the environment specific erun script will not copy any behaviour from the generic erun script of the same name.

== Licence

GPLv3

== Author

http://bguiz.com[Brendan Graetz]