Navy Penguin Mariachi


    3.1.2 • Public • Published

    habitat Build Status

    Version 3.0.0

    Library for managing your environment vars.


    According to factor 3, you should be storing your configuration as environment variables. Writing process.env everywhere can be real annoying, so this abstracts away of that manipulation. It also provides some nice little nicities for testing.


    Why NPM of course!

    $ npm install habitat


    new habitat([prefix, [defaults]])

    Creates a new environment manipulator.

    prefix is the prefix for your environment variables. For example, if your app is called airsupport, it's probably good to namespace your environment variables like so:

    export AIRSUPPORT_HOST='lolcathost'
    export AIRSUPPORT_PORT=3000

    In this case, you would use new habitat('airsupport') -- the prefix will be auto-capitalized because only barbarians use lowercase letters in their environment variables.

    defaults is an object representing the defaults if a key cannot be found in the environment. This should be used sparingly.

    var env = new habitat('airsupport', { port: 1024 })
    // will try the environment first, then fall back to 1024
    var port = env.get('port');

    habitat#get(key, [default])

    Gets a key from the environment. Automatically prefixes with the prefix passed to the constructor, if necessary.

    habitat#get will also try to do some parsing of the value if it looks like a boolean, number or json, so you can do things like this:

    export APP_ADMINS='["", ""]'
    var env = new habitat('app');
    var admins = env.get('admins');
    console.log(admins.indexOf('')) // 1

    If a default is passed, if the key is undefined in either the env or the constructor-set defaults, it will fall back to that.

    Getting objects

    get will automatically return objects if you take advantage of common prefixing:

    export APP_DB='redis'
    export APP_REDIS_HOST=''
    export APP_REDIS_PORT=6379
    var env = new habitat('app');
    var db = env.get('db');
    var options = env.get(db);
    console.log(; // ''
    console.log(options.port); // 6379

    Getting keys using camelCase

    You can also use camelcase instead of underscores if you want, habitat's got your back.

    export APP_SOME_LONG_KEY='great'
    var env = new habitat('app');
    console.log(env.get('someLongKey')) // 'great'


    You can also use get directly from the habitat object to get unprefixed things from the environment.

    var path = habitat.get('path');
    var nodeEnv = habitat.get('nodeEnv');


    Try to load a set of environment variables from a file. This will not override whatever is in the environment. This is a change from Habitat v1.x's behaviour. This means that you can chain multiple environment files together to provide sane defaults for your local development or to commit environment configuration into your repository:


    Environment file can be in the form of exports:

    # /some/directory/.env 
    # The leading `export` is optional. 
    # Useful if you want to be able to also `source /some/directory/.env` 
    export PARAMETER_ONE=one
    export PARAMETER_TWO=two

    It can also take JSON if you're into that:

    {"parameterOne": "one",
     "parameterTwo": "two"}
    var env = habitat.load('/some/directory/.env'); // returns true on success
    console.dir(env.get('parameter')); // { one: 'one', two: 'two' }

    pathToEnvFile defaults to '.env', which will just look for a .env file in the current working directory.

    habitat#set(key, value)

    Sets an environment variable, with prefix if passed.


    Unsets an environment variable


    Get an object with all of the things in the environment.

    If options.raw is true, returns all values as strings. Otherwise, habitat will try to parse them as number, json, or boolean, as in habitat#get.


    export APP_HOST='localhost'
    export APP_PORT=3000
    export APP_PROTO=http
    var env = new habitat('app');
    var obj = env.all();
    console.log(; // 'localhost'

    habitat#temp(object, callback)

    Temporarily overrides environment variables with values from object.

    callback can be syncronous if defined without any parameters, or async if defined with a single parameter.


    var env = new habitat('airsupport', {
      protocol: 'http',
      host: '',
      port: 3000
    var tempEnv = {
      host: 'lolcathost'
      port: 5000
    // sync
    env.temp(tempEnv, function() {
      console.log(env.get('host')) // "lolcathost"
      console.log(process.env['AIRSUPPORT_HOST']) // "lolcathost"
    console.log(env.get('host')) // ""
    // async
    env.temp(tempEnv, function(done)
        console.log(env.get('port')) // 5000




    npm i habitat

    DownloadsWeekly Downloads






    Last publish


    • brianloveswords
    • jbuck