Solving the Environmental Variable Problem

 The Problem

Recently I have come across a problem whilst developing twelve factor applications in node. ( Side not - if you don't use the 12 factor app you should - link here )

The problem is that we use several different packages to build our application, taking full advantage of the awesome NPM private modules that were recently released. The problem was that it has become increasingly hard to keep track of what environmental variables were required to make the project function, or were just generally available, because they were all being accessed at different levels of the applications dependency tree.

This further led to a problem of completely entangled documentation where the parent app's documentation had to be updated to match any change in environmental variable documentation anywhere in its dependancy tree. Not good at all!

The Solution

Over the course of Sunday afternoon I built a small CLI tool in my beloved Node.js that has two roles. First, it defines a JSON format for a NPM package to declare its environmental variables.

I think the format is a pretty neat, here is an example of an environmentalist.json:

        “name”: “PASSWORD_HASH_SECRET”,
        “description”: “Used to compute the password hash of users”,
        “default”: “ABCDEFGHIJKLMOP”,
        “required”: true
        “name”: “LOG_LEVEL”,
        “description”: “Sets the level that will be logged by the system”,
        “default”: “info”,
        “required”: false
        “name”: “CRAZY_VARIABLE” 

Once you have got your package setup with one of these environmentalist.json files, you can then use the CLI tool to get an overview of all the environmental variables , a description of what they do and whether they are required. The added benefit is you do not have to worry where in your dependancy tree they came from, you simply get to see all environmental variables that are available to the application.

To install the cli, simply run:

npm install -g environmentalist  

After it is installed you can simply run:


in any directory to get a summary of the environmental variables available.

Head over to the NPM page or GitHub page for more info.

Bonus Round

Environmentalist is just a format and a simple CLI tool. It is not bound to node and can be used for any application using any language. The important thing for environmentalist is adoption! If packages don't support it then the usefulness of the tool is more limited.

Granted it's still super useful for internal stuff.


I would love to hear if this is a problem anyone else has had! If this is something you have experienced feel free to get in touch. I recommend opening an issue on GitHub or emailing me at [email protected]