easyconfig v1.0.0-1
EasyConfig
Easy configuration for node.js, inspired by node-config .
Install
npm i easyconfig
Quick start
Example file structure:
.
├── config
│ ├── default.js
│ ├── development.json
│ └── production.js
└── index.js
// Default is development
node index.js
// or
NODE_ENV=production node index.js
Usage
require([BASEDIR, [NAME, [OPTIONS]]])
// or
require(OPTOINS)
Available options:
name
: the configuration name you want to load (same asNODE_CONFIG_ENV
,NODE_ENV
).basedir
: if it'snull
, will useprocess.cwd()
, if usingEasyConfig
in main module, just keep it empty, otherwise, pass__dirname
toEasyConfig
. We will explain it later.instance
: same asNODE_APP_INSTANCE
.hostname
: same asHOST
,HOSTNAME
,os.hostname()
.subModuleMode
: enable sub module mode.
Configuration files must be stored in config
folder.
Supported Environment Variables
EasyConfig
will use variables from process.env
to load configuration files:
NODE_CONFIG_ENV
,NODE_ENV
NODE_APP_INSTANCE
HOST
,HOSTNAME
,os.hostname()
Load priority is lowered from left to right.
Environment variables can be changed when needed to:
require('easyconfig')(__dirname, 'production', { instance: 1 })
require('easyconfig')({
name: 'production',
instance: 2,
hostname: 'example.com'
})
Load Order
default.EXT
default-{instance}.EXT
{deployment}.EXT
{deployment}-{instance}.EXT
{short_hostname}.EXT
{short_hostname}-{instance}.EXT
{short_hostname}-{deployment}.EXT
{short_hostname}-{deployment}-{instance}.EXT
{full_hostname}.EXT
{full_hostname}-{instance}.EXT
{full_hostname}-{deployment}.EXT
{full_hostname}-{deployment}-{instance}.EXT
local.EXT
local-{instance}.EXT
local-{deployment}.EXT
local-{deployment}-{instance}.EXT
custom-environment-variables.EXT
EXT
can be cson
, js
, json
, properties
, toml
, xml
, or yaml
.
How It Works
Exampla file structure:
.
├── mian-module
│ ├── config
│ ├── index.js
│ └── node_modules
│ └── sub-module-a
│ ├── config
│ └── index.js
└── sub-module-b
├── config
└── index.js
In main module
main-module/index.js
:
const config = require('easyconfig')()
const subModuleA = require('sub-module-a')
const app = new require('koa')
app.use(subModuleA())
In sub module
For sub module, EasyConfig
will:
- Try to determine its root dir (which contains a
package.json
file). - If failed to resolve root dir, use
process.cwd()
instead.
When root dir is found,
- Load configuration files from module root dir.
- Load configuratino files from
process.cwd()
.
sub-module-a/index.js
:
// config has all the props from `sub-module-a/config` and `main-module/config`
const config = require('easyconfig')(__dirname)
There's two use cases that EasyConfig
suits for:
Sub module has its own configuration, but needs environment variables
sub-module-a/index.js
,
const config = require('easyconfig')(__dirname)
EasyConfig
will merge main module's configuration into sub modules's: merge({}, main_module_config, sub_module_a_config)
.
In this way, you can use environment variables in sub module:
.
└── sub-module
└── config
├── development.js
└── production.js
Sub module has default configuration and allow parent module to configure it
In sub-module-a/index.js
,
const config = require('easyconfig')({
basedir: __dirname,
subModuleMode: 'fieldName'
})
EasyConfig
will merge sub module's configuration with main module's: merge({}, sub_module_a_config, main_module_config)
.
If pass a string to subModuleMode
, EasyConfig
will treat it as a property name, and only load value with this property name from main module.
For example, main module's config:
{
subModule: {
port: 2345
}
port: 1234,
host: 'example.com'
}
Sub module:
const config = require('easyconfig')({
basedir: __dirname,
subModuleMode: 'subModule'
})
assert(config.port === 2345)
assert('host' in config === false)
Property Descriptor
EasyConfig
respects property descriptor, so you can do things like this:
In default.js
:
module.exports = {
get foo () {
return `${this.bar}/${this.baz}`
}
}
In other files:
module.exports = {
bar: 'bar',
baz: 'baz'
}
const config = EasyConfig()
assert(config.foo === 'bar/baz')