configly

configly

A simple configuration management module used for node.js projects.

Installation

$ npm install configly --save

Usage

1. After installing the configly package (see above), Create a directory in the root of your project called config.

2. Put configuration files in your newly created config directory

   • Filenames should be all lowercase letters with words separated by -
   • The configuration files should be a .json file or .js file
   • .js files should module.exports = the config object
   • Environment config files should be named as such: env.[environmentName].json or env.[environmentName].js.
   • The default environment is development.
   • To use a different environment config file, start your node app like this:

   $ NODE_ENV=production node app
   

   replacing production with the environment you wish be in.

3. Include the config object in your files:

   var config = require('configly');
   

The config object return will reflect the data put into your configuration files.

Each of the files is a property attached to the config object. The property name is a camelCased version of the name (e.g. filename = foo-bar.json, config = { fooBar: ... } see example below).

The environment config gets put in as the env property.

Example

Imagine a directory structure like this:

project/
├─ config/
│  ├─ env.development.json
│  ├─ env.production.json
│  ├─ user-permissions.json
│  └─ email.js
├─ node_modules/
│  └─ configly/...
├─ package.json
└─ app.js

config/env.development.json

{
  "port": "3000",
  "cachAge": 0
}

config/env.production.json

{
  "port": "80",
  "cacheAge": 86000
}

config/user-permissions.json

{
  "/": [
    "admin",
    "anonymous"
  ],
  "/admin": [
    "admin"
  ]
}

config/email.js

'use strict';

var emailConfig = {};

emailConfig.user = '[e-mail]';
emailConfig.password = 'my super secure password';

module.exports = emailConfig;

app.js

'use strict';

var config = require('configly');

console.log(config);

Alright, now with that setup, we run this command:

$ node app

We get this output:

{ email:
   { user: '[e-mail]',
     password: 'my super secure password' },
  env: { port: '3000', cachAge: 0, name: 'development' },
  userPermissions: { '/': [ 'admin', 'anonymous' ], '/admin': [ 'admin' ] } }

But when we run this command:

$ NODE_ENV=production node app

We get this ouput:

{ email:
   { user: '[e-mail]',
     password: 'my super secure password' },
  env: { port: '80', cacheAge: 86000, name: 'production'},
  userPermissions: { '/': [ 'admin', 'anonymous' ], '/admin': [ 'admin' ] } }

Notice the only change was in the environment variable. I don't know about you, but this is super handy, because now deployment becomes a breeze.

Any file you add to the config directory will automatically be added to the config object. No need to include it in some master config file.

Also, no 3rd party dependencies. The only core dependencies it has are fs and path.

Troubleshooting

If there is some behavior that isn't expected, like the config object isn't in the format you expected, try console.log on the config object.

If there is no config directory in what is considered your 'current working directory' (this can be found by process.cwd()), then the config object will be a javascript Error object.

If there was an error parsing the .json or .js, then the property that it was supposed to be in will be a SyntaxError object.

Any other issues, please report to this repo's issues on GitHub.

Caveats

Although you can a config file with the same name but have different extentions (i.e. .js and .json), you shouldn't because one of them will not be included. From the tests that I've done, it takes the .json version because it shows up later in the list. At any rate, it seems like it would be bad practice to have two files with the same name in the same directory.

Your config directory has to be where your process.cwd() resides. In the future, I would like this to be configurable, but in the spirit of quick iterations and getting feedback, I will save that for another day.

Development

This project uses gulp for task automation.

$ npm install -g gulp

Here are the three tasks available to use:

• gulp hint: runs all pertinent code against jshint. The rules are the ones defined in .jshintrc

• gulp test: runs all tests with mocha for passing and instanbul for code coverage. It generates html files showing the code coverage.

• gulp docs: builds out all of the documentation using docco. Note that you need to have docco installed (npm install -g docco). I at one time at docco part of the dev dependencies, but now I don't. I may be open to putting it back, but I just wanted to keep the package as small as possible.

You can also run npm test, and it does basically does the same thing as gulp test, but an error will be thrown because it does some more istanbul stuff to send data to the coverage server. When this project runs through travis, it also sends coverage data to coveralls.io.

When forking and doing pull requests, work off of the develop branch. I won't be super strict on this, but it's what I would prefer. That way we can keep master clean.