common-env configuration through environment variables finally done right.
Philosophy
Here is my principle:
See the talk (in french) about the why [15:23-21:30]
* besides i18n translation key and things like that of course (well, now that we've got symbols in ES6...)
NPM
npm install common-env
Usage
var env = ;var config = env; t; // converted from env
env.getOrDie(envVarName)
env.getOrElse(envVarName, default)
env.getOrElseAll(object)
getOrElseAll
allows you to specify a configuration object with default values that will be resolved from environment variables.
Let say we start a script with AMQP_LOGIN=plop AMQP_CONNECT=true AMQP_EXCHANGES[0]_NAME=new_exchange FACEBOOK_SCOPE="user,timeline" FACEBOOK_BACKOFF="200,800" node test.js
with test.js
defined as follow:
var env = ; var config = env; t; // extracted and converted from envt;t; // extracted and converted from envt; // extracted from envt;t; // extracted and converted from envt; // extracted and converted from env
Events
Common-env will emit the following events:
env:fallback(key, $default)
: each time a environment key was not found and that common-env fallback on$default
.env:found(key, value, $default)
// let say NODE_ENV was set to "production" var env = ; var config = env ; // Will print // [env] NODE_ENV was defined, using: production// [env] REDSMIN_GC_ENABLED was not defined, using default: false
Specifying multiple aliases
It's sometimes useful to be able to specify aliases, for instance Clever-cloud or Heroku expose their own environment variable names while your application's internal code may not want to rely on them. You may not want to depend on your hosting provider conventions.
Common-env adds a layer of indirection enabling you to specify environment aliases that won't impact your codebase.
How to handle environment variable arrays
Since v6, common-env is able to read arrays from environment variables. Before going further, please don't forget that environment variables do not support arrays, thus MY_ENV_VAR[0]_A
is not a valid environment variable name, as well as MY_ENV_VAR$0$_A
and so on. In fact, the only supported characters are [0-9_]
. But since we wanted a lot array support we had to find a work-around.
And here is what we did:
Configuration key path | Generated environment key |
---|---|
amqp.exchanges[0].name | AMQP_EXCHANGES__0_NAME |
amqp.exchanges[10].name | AMQP_EXCHANGES__10_NAME |
As you can see, we a replacing [0]
, with __0
and thus common-env is compliant with the limited character support while providing an awesome abstraction for configuration through environment variables.
Note that only the first element of the array will be used as a description for every other element of the array. So in the following code:
const config = env;
only the first object
{ host: '127.0.0.1', port: 3306 }
will be used as a type template for every defined elements.
One last thing, common-env is smart enough to build plain arrays (not sparse), so if you defined MYSQL_HOSTS__10_PORT=3310
, config.mysql.hosts
will contains 10 objects as you thought it would.
How to specify environment variable arrays
Common-env is able to use arrays as key values for instance:
// test.jsvar env = ;var config = env; console;
Running the above script we can override amqp.hosts
values with the AMQP_HOSTS
environment variable we get:
$ node test.js['192.168.1.1', '192.168.1.2']$ AMQP_HOSTS='127.0.0.1' node test.js['127.0.0.1']$ AMQP_HOSTS='88.23.21.21,88.23.21.22,88.23.21.23' node test.js['88.23.21.21', '88.23.21.22', '88.23.21.23']
How to specify environment variable arrays using $aliases
// test.jsvar env = ;var config = env; console;
Running the above script we can override amqp.hosts
values with the ADDON_RABBITMQ_HOSTS
or LOCAL_RABBITMQ_HOSTS
environment variable aliases we get:
$ node test.js['192.168.1.1', '192.168.1.2']$ ADDON_RABBITMQ_HOSTS='127.0.0.1' node test.js['127.0.0.1']$ LOCAL_RABBITMQ_HOSTS='88.23.21.21,88.23.21.22,88.23.21.23' node test.js['88.23.21.21', '88.23.21.22', '88.23.21.23']
Aliases don't supports arrays in their names and never will.
fail-fast behaviour
If $default
is not defined and no environment variables (aliases included) resolve to a value then common-env will throw an error. This error should not be caught in order to make the app crash, following the fail-fast principle.
How to define type converters
Since common-env uses $default
to infer the environment variable type, if $default
is not available common-env won't be able to use the right type, for instance:
// ...var config = env;
config.redis.ports
should be an array of number but instead common-env will fallback to a string because it can't infer what should be the type of config.redis.ports
. That's where $type
is handy if gives you a way to tell common-env how it should convert the value:
// ...var config = env
Note that $aliases
isn't mandatory with $type
.
As of today, currently supported types are:
env.types.String
env.types.Integer
env.types.Float
env.types.Boolean
env.types.Array(env.types.String)
env.types.Array(env.types.Integer)
env.types.Array(env.types.Float)
env.types.Array(env.types.Boolean)
How common-env resolves environment variables
Let's take the following configuration object:
amqp: login: $default: 'guest' $aliases: 'ADDON_RABBITMQ_LOGIN' 'LOCAL_RABBITMQ_LOGIN' password: 'guest' host: 'localhost' port: 5672
Here is how common-env will resolve amqp.login
:
- Common-env will first read
ADDON_RABBITMQ_LOGIN
environment variable, if it exists, its value will be used. - If not common-env will read
LOCAL_RABBITMQ_LOGIN
, if it exists, its value will be used. - If not common-env will read
AMQP_LOGIN
, if it exists, its value will be used. - If not common-env will fallback on
$default
value.
How to retrieve old common-env logging behaviour
Common-env 1.x.x-2.x.x was displaying logs, here is how to retrieve the same behaviour in 3.x.x.
var logger = console;var config = logger;
How to set silent (or secure) values in output logger
var logger = console;var config = logger; // Console output:// [env] AMQP_PASSWORD was not defined, using default: ***"// [env] AMQP_PASSWORD was defined, using: ***"
Changelog
Donate
I maintain this project in my free time, if it helped you please support my work via paypal or Bitcoins, thanks a lot!