\n\n[](https://circleci.com/gh/FGRibreau/common-env/) [](https://coveralls.io/github/FGRibreau/common-env?branch=master) [](https://david-dm.org/FGRibreau/common-env) [](http://badge.fury.io/js/common-env) [](https://www.npmjs.com/package/common-env)\n\n[](https://www.codementor.io/francois-guillaume-ribreau?utm_source=github&utm_medium=button&utm_term=francois-guillaume-ribreau&utm_campaign=github) [](http://bit.ly/2c7uFJq) \n\n# Philosophy\n\nHere is my principle:\n\n[](https://www.uslide.io/presentations/Aw6sX5ug-Tfzw5rNXAmdJg)\n\n[See the talk (in french) about the why [15:23-21:30]](https://www.uslide.io/presentations/Aw6sX5ug-Tfzw5rNXAmdJg)\n\n\\* besides i18n translation key and things like that of course (well, now that we've got symbols in ES6...)\n\n# NPM\n\n```shell\nnpm install common-env\n```\n\n#### Usage\n\n```javascript\nvar env = require('common-env')();\nvar config = env.getOrElseAll({\n amqp: {\n login: {\n $default: 'guest',\n $aliases: ['ADDON_RABBITMQ_LOGIN', 'LOCAL_RABBITMQ_LOGIN']\n },\n password: 'guest',\n host: 'localhost',\n port: 5672\n }\n});\n\nt.strictEqual(config.amqp.login, 'plop'); // converted from env\n```\n\n\n#### env.getOrDie(envVarName)\n\n#### env.getOrElse(envVarName, default)\n\n#### env.getOrElseAll(object)\n\n`getOrElseAll` allows you to specify a configuration object with default values that will be resolved from environment variables.\n\nLet 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:\n\n```javascript\nvar env = require('common-env')();\n\nvar config = env.getOrElseAll({\n amqp: {\n login: 'guest',\n password: 'guest',\n host: 'localhost',\n port: 5672,\n connect: false,\n exchanges:[{\n name: 'first_exchange'\n },{\n name: 'second_exchange'\n }]\n },\n\n FULL_UPPER_CASE: {\n PORT: 8080\n },\n\n facebook:{\n scope:['user', 'timeline', 'whatelse'],\n backOff: [200, 500, 700]\n },\n\n MICROSTATS: {\n HASHKEY: 'B:mx:global'\n }\n});\n\nt.strictEqual(config.amqp.login, 'plop'); // extracted and converted from env\nt.strictEqual(config.amqp.port, 5672);\nt.strictEqual(config.amqp.connect, true); // extracted and converted from env\nt.strictEqual(config.amqp.exchanges[0].name, 'new_exchange'); // extracted from env\nt.strictEqual(config.FULL_UPPER_CASE.PORT, 8080);\nt.strictEqual(config.facebook.scope, ['user', 'timeline']); // extracted and converted from env\nt.strictEqual(config.facebook.backoff, [200, 800]); // extracted and converted from env\n```\n\n#### Events\n\nCommon-env will emit the following events:\n\n- `env:fallback(key, $default)`: each time a environment key was not found and that common-env fallback on `$default`.\n- `env:found(key, value, $default)`\n\n```javascript\n// let say NODE_ENV was set to \"production\"\n\nvar env = require('common-env')();\n\nvar config = env\n .on('env:found', function (fullKeyName, value, $secure) {\n value = $secure ? '***' : value;\n console.log('[env] %s was defined, using: %s', fullKeyName, String(value));\n })\n .on('env:fallback', function (fullKeyName, $default, $secure) {\n $default = $secure ? '***' : $default;\n console.log('[env] %s was not defined, using default: %s', fullKeyName, String($default));\n })\n .getOrElseAll({\n node: {\n env: 'production'\n },\n redsmin: {\n gc: {\n enabled: false\n }\n }\n });\n\n// Will print\n\n// [env] NODE_ENV was defined, using: production\n// [env] REDSMIN_GC_ENABLED was not defined, using default: false\n```\n\n#### Specifying multiple aliases\n\nIt's sometimes useful to be able to specify aliases, for instance [Clever-cloud](http://clever-cloud.com) or [Heroku](https://heroku.com) 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.\n\nCommon-env adds a [layer of indirection](http://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering) enabling you to specify environment aliases that won't impact your codebase.\n\n#### How to handle environment variable arrays\n\nSince **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](https://github.com/FGRibreau/common-env/issues/6).\n\nAnd here is what we did:\n\n| Configuration key path | Generated environment key |\n|---|---|\n| amqp.exchanges[0].name | AMQP_EXCHANGES__0_NAME |\n| amqp.exchanges[10].name | AMQP_EXCHANGES__10_NAME |\n\nAs 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.\n\nNote 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:\n\n```js\nconst config = env.getOrElseAll({\n mysql: {\n hosts: [{\n host: '127.0.0.1',\n port: 3306\n }, {\n auth: {\n $type: env.types.String,\n $secure: true\n }\n }]\n }\n});\n```\n\nonly the first object\n\n`{\n host: '127.0.0.1',\n port: 3306\n}`\n\nwill be used as a *type* template for every defined elements.\n\nOne 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.\n\n#### How to specify environment variable arrays\n\nCommon-env is able to use arrays as key values for instance:\n\n```javascript\n// test.js\nvar env = require('common-env')();\nvar config = env.getOrElse({\n amqp:{\n hosts:['192.168.1.1', '192.168.1.2']\n }\n});\n\nconsole.log(config.amqp.hosts);\n```\n\nRunning the above script we can override `amqp.hosts` values with the `AMQP_HOSTS` environment variable we get:\n\n```shell\n$ node test.js\n['192.168.1.1', '192.168.1.2']\n$ AMQP_HOSTS='127.0.0.1' node test.js\n['127.0.0.1']\n$ AMQP_HOSTS='88.23.21.21,88.23.21.22,88.23.21.23' node test.js\n['88.23.21.21', '88.23.21.22', '88.23.21.23']\n```\n\n#### How to specify environment variable arrays using $aliases\n\n```javascript\n// test.js\nvar env = require('common-env')();\nvar config = env.getOrElse({\n amqp:{\n hosts:{\n $default: ['192.168.1.1', '192.168.1.2'],\n $aliases: ['ADDON_RABBITMQ_HOSTS', 'LOCAL_RABBITMQ_HOSTS']\n }\n }\n});\n\nconsole.log(config.amqp.hosts);\n```\n\nRunning the above script we can override `amqp.hosts` values with the `ADDON_RABBITMQ_HOSTS` or `LOCAL_RABBITMQ_HOSTS` environment variable aliases we get:\n\n```shell\n$ node test.js\n['192.168.1.1', '192.168.1.2']\n$ ADDON_RABBITMQ_HOSTS='127.0.0.1' node test.js\n['127.0.0.1']\n$ LOCAL_RABBITMQ_HOSTS='88.23.21.21,88.23.21.22,88.23.21.23' node test.js\n['88.23.21.21', '88.23.21.22', '88.23.21.23']\n```\n\nAliases don't supports arrays in their names and never will.\n\n\n##### fail-fast behaviour\n\nIf `$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](https://en.wikipedia.org/wiki/Fail-fast) principle.\n\n### How to define type converters\n\nSince 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:\n\n```js\n// ...\nvar config = env.getOrElseAll({\n redis:{\n hosts: {\n $aliases: ['REDIS_ADDON_PORTS']\n }\n }\n});\n```\n\n`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:\n\n```js\n// ...\nvar config = env.getOrElseAll({\n redis:{\n hosts: {\n $aliases: ['REDIS_ADDON_PORTS'],\n $type: env.types.Array(env.types.Number)\n }\n }\n```\n\n*Note that `$aliases` isn't mandatory with `$type`.*\n\nAs of today, currently supported types are:\n\n- `env.types.String`\n- `env.types.Integer`\n- `env.types.Float`\n- `env.types.Boolean`\n- `env.types.Array(env.types.String)`\n- `env.types.Array(env.types.Integer)`\n- `env.types.Array(env.types.Float)`\n- `env.types.Array(env.types.Boolean)`\n\n\n#### How common-env resolves environment variables\n\nLet's take the following configuration object:\n\n```javascript\n{\n amqp: {\n login: {\n $default: 'guest',\n $aliases: ['ADDON_RABBITMQ_LOGIN', 'LOCAL_RABBITMQ_LOGIN']\n },\n password: 'guest',\n host: 'localhost',\n port: 5672\n }\n}\n```\n\nHere is how common-env will resolve `amqp.login`:\n\n- Common-env will first read `ADDON_RABBITMQ_LOGIN` environment variable, if it exists, its value will be used.\n- If not common-env will read `LOCAL_RABBITMQ_LOGIN`, if it exists, its value will be used.\n- If not common-env will read `AMQP_LOGIN`, if it exists, its value will be used.\n- If not common-env will fallback on `$default` value.\n\n
\n\n
\n\n\n#### How to retrieve old common-env logging behaviour\n\nCommon-env 1.x.x-2.x.x was displaying logs, here is how to retrieve the same behaviour in 3.x.x.\n\n```javascript\nvar logger = console;\nvar config = require('common-env/withLogger')(logger).getOrElseAll({\n amqp: {\n login: {\n $default: 'guest',\n $aliases: ['ADDON_RABBITMQ_LOGIN', 'LOCAL_RABBITMQ_LOGIN']\n },\n password: 'guest',\n host: 'localhost',\n port: 5672\n }\n});\n\n```\n\n#### How to set silent (or secure) values in output logger\n\n```javascript\nvar logger = console;\nvar config = require('common-env/withLogger')(logger).getOrElseAll({\n amqp: {\n password: {\n $default: 'guest',\n $secure: true\n }\n }\n});\n\n// Console output:\n// [env] AMQP_PASSWORD was not defined, using default: ***\"\n// [env] AMQP_PASSWORD was defined, using: ***\"\n```\n\n#### [Changelog](/CHANGELOG.md)\n\n## Donate\n\nI maintain this project in my free time, if it helped you please support my work [via paypal](https://paypal.me/fgribreau) or [Bitcoins](https://www.coinbase.com/fgribreau), thanks a lot!\n","maintainers":[{"name":"fgribreau","email":"npm@fgribreau.com"}],"time":{"modified":"2022-06-13T06:35:43.339Z","created":"2014-12-23T21:46:05.003Z","1.0.0":"2014-12-23T21:46:05.003Z","1.1.0":"2015-01-14T09:00:36.259Z","1.2.0":"2015-03-26T09:40:53.704Z","1.2.1":"2015-04-22T15:11:55.123Z","2.0.0":"2015-04-22T15:23:50.992Z","2.1.0":"2015-05-18T14:23:47.418Z","2.1.1":"2015-05-18T14:25:10.605Z","2.2.0":"2015-05-19T14:01:22.728Z","3.0.0":"2015-05-19T16:08:03.832Z","3.0.1":"2015-05-19T16:10:54.393Z","4.0.0":"2015-05-19T16:21:58.505Z","4.0.1":"2015-05-20T08:31:56.397Z","4.1.0":"2015-07-02T13:52:36.118Z","5.0.0":"2015-08-24T16:11:55.469Z","5.1.0":"2015-11-04T16:58:22.946Z","5.2.0":"2015-11-10T14:47:31.371Z","5.2.1":"2016-01-25T08:28:07.743Z","5.3.0":"2016-07-29T17:27:26.075Z","5.4.0":"2016-08-08T13:15:28.950Z","6.0.0":"2016-08-23T15:07:45.166Z","6.0.1":"2016-11-02T14:56:10.486Z","6.1.0":"2016-11-22T16:07:59.647Z","6.2.0":"2018-10-24T19:35:28.600Z","6.3.0":"2018-10-29T17:55:27.881Z","6.3.1":"2019-12-23T16:13:54.762Z","6.4.0":"2020-06-02T19:06:20.390Z"},"homepage":"https://github.com/FGRibreau/common-env","repository":{"type":"git","url":"git+https://github.com/FGRibreau/common-env.git"},"author":{"name":"Francois-Guillaume Ribreau","email":"npm@fgribreau.com","url":"http://fgribreau.com/"},"bugs":{"url":"https://github.com/FGRibreau/common-env/issues"},"license":"MIT","readmeFilename":"README.md","keywords":["environment","configuration","process.env","env","var","getenv","variables"],"users":{"feedhenry":true}}
![\"\"](\"https://cdn.rawgit.com/egoist/fa2efce43aa2f62e39bbc363bf2240b7/raw/c17a8a5bf5981c32d7b38bbf2dcd88866ef1c8b1/gear.svg\")
\n ![](\"./docs/Thumbs-Up-Gif.gif\"/)
\n