confix
Common configuration utilities and helpers for applications
Installation
Node
$ npm install --save confix
Defining Your Configuration
Configuration Files
confix
requires you to define your configuration in files using the JSON
format. All files conforming to the JSON
format are valid configuration files.
Storing Configuration
Within your application directory structure, designate a sub-directory to hold configuration files. All configuration files must reside within this directory for confix
to access them.
Each configuration file must have the extension .json
for confix to read it. The name of the file will be the baseName for configuration configuration. For example, naming your configuration file server.json
would mean the baseName for that configuration is server
.
You may choose to store all configuration values in one configuration file. However we recommend you consider logically split your configuration values baed on your application. For example, we could create configuration for a web-application as follows:
server.json
- stores the configuration values for theexpress
server.redis.json
- stores the configuration values forredis
server.db.json
- store configuration values for database connectivity
Environment Specific Settings
Every application may have configuration values which vary between different environments. To accomodate this, confix
supports file-names which contain the name of the environment suffixed to the baseName. For example:
server.json
- the common configuration available in all environments.server.development.json
- the configuration values for thedevelopment
environment.server.testing.json
- the configuration values for thetesting
environment.server.production.json
- the configuration values for theproduction
environment.
Environment labels are not limited to the above examples. You may choose any label for your environment you wish.
confix
uses the environment variable NODE_ENV
to detect the environment in which the application is running via process.env
. If NODE_ENV
is not set, the environment defaults to development
.
Order of Configuration Overrides
Environment specific configuration files can override common settings. Below is the order confix
uses to select environment specific settings:
- First retrieve all configuration values from
<baseName>.json
configuration file. - If it exists, retrieve all configuration values from
<baseName>.<environment>.json
configuration file. - Merge configuration values retrieved from
<baseName>.json
, overriding those whose keys are also available in this file.
Therefore the <baseName>.json
file is a good place to put configuration values common to all environments.
Injecting Environment Variables
confix
also provides the ability to inject system environment variables for configuration values. You can accomplish this by delimiting your configuration values between a pair of {}
. Example:
In the above example, the host
configuration key will get a value localhost
if the APP_HOST
system environment variable is set to the same.
Usage
var confix = ; var cfg serverConfig redisConfig; // initialize confix to point to the directory containing the configuration filesconfix; // assuming we have server.json, redis.json in our configuration files directoryserverConfig = confix;redisConfig = confix; // retrieves both server and redis configuration valuescfg = config; serverConfig; // contains all configuration values from server.jsonredisConfig; // contains all configuration values from redis.json cfgserver; // contains all configuration values from server.jsoncfgredis; // contains all configuration values from redis.json
License
Copyright (c) 2015, intuitivcloud Systems <engineering@intuitivcloud.com> All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
Neither the name of signalman nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.