node-etc

Configuration loader for node.js applications.

Idea

Your application probably needs to load configuration from multiple sources and make them available as one object. Etc is here to help!

Etc provides a fairly complete API for loading configuration from a variety of sources, however, its been engineered to easily load config from (in order of precedence): argv, environment, files in /etc/, package.json, and defaults.

Etc. also allows you to edit and save your configuration.

When relative path is supplied for fileName in any of the functions, the file is looked for in (order) in:

1. the cwd path moving down one level till it is found
2. /etc/${appName}
3. ~/etc/${appName}
4. {projectRoot}/etc
5. {projectRoot}/.etc
6. {projectRoot}/config
7. {projectRoot}/config

Preparatory

Remember to change cwd to the root of your application so node-etc does not fail for global packages. Do this by setting the following in you entry js file

process.chdir(__dirname);

Examples

Create configuration

const conf = require('node-etc');

// supply absolute path. If script is not run as sudo, the file will be created in ~/etc/${appName}/conf.yaml
const appName = conf.packageJson().name
conf.createConfig(`/etc/${appName}/conf.yaml`);

// filename supplied. creates config file in root directory of your project
conf.createConfig('conf2.yaml');

Get Root Directory of Your project

const conf = require('node-etc');

const rootDir = conf.projectRoot()
console.log(rootDir)

read package.json

const conf = require('node-etc');

// from current project
conf.packageJson();

// from absolute path
conf.packageJson('/home/brian/Code/CSECO/csycms'); // will read /home/brian/Code/CSECO/csycms/package.json

// from /etc/ ~/etc
conf.packageJson('CSECO'); // will read /etc/${appName}/CSECO/package.json or ~/etc/${appName}/CSECO/package.json

read json file

const conf = require('node-etc');

// from absolute path
let output = conf.parseJSON('/home/brian/Code/CSECO/csycms'); // will read /home/brian/Code/CSECO/csycms.json
console.log(output)
// from /etc/ ~/etc
output = conf.parseJSON('CSECO'); // will read /etc/${appName}/CSECO.json or ~/etc/${appName}/CSECO.json
console.log(output)

read yaml file

const conf = require('node-etc');

// from absolute path
let output = conf.parseYAML('/home/brian/Code/CSECO/csycms'); // will read /home/brian/Code/CSECO/csycms.yaml/.yml
console.log(output)
// from /etc/ ~/etc
output = conf.parseYAML('CSECO'); // will read /etc/${appName}/CSECO.json or ~/etc/${appName}/CSECO.yaml/.yml
console.log(output)

add values to configuration

const conf = require('node-etc');

conf.addConfig('yaml', '/etc/node-etc/conf.yaml', { Field: "value", Ta: "bitha" }));
conf.addConfig('env', '/etc/node-etc/.env', { Field: "value", Ta: "bitha" }));

Load configuration from argv, env, a file, and defaults.

const conf = require('node-etc');

// read package.json
conf.packageJson('/home/brian/Code/CSECO/csycms');
conf.packageJson('CSECO');
conf.packageJson();


conf.argv());

// read all enviroment values
conf.env());

// read from yaml
conf.parseYAML('/etc/node-etc/conf.yml');
conf.parseYAML('conf.yml');
conf.parseYAML();

// read all possible configuration files from directory
conf.directory('/etc/node-etc');

API

Refer to the documentation

etc

Kind: global class

• etc
  • new etc()
  • .createConfig(filePath)
  • .packageJson([dir]) ⇒ object
  • .projectRoot() ⇒ string
  • .parseJSON(filePath) ⇒ object
  • .argv() ⇒ object
  • .directory(dir) ⇒ object
  • .parseYAML([filePath]) ⇒ object
  • .env([dir]) ⇒ object
  • .getFilePath(configType, fileName)
  • .readConfigData(configType, filePath, config)
  • .addConfig(configType, filePath, config)
  • .deleteConfig(configType, filePath, config)
  • .editConfig(configType, filePath, config)
  • .save(configType, filePath, config)
  • .all()

new etc()

constructor

etc.createConfig(filePath)

create configuration file in filePath if it does not exists

Kind: instance method of etc

| Param | Type | Description | | --- | --- | --- | | filePath | string | with the extensions [.json|.yaml|.yml|.env]if filename is supplied instead of absolute path, create in /etc/{appName} or in ~/etc/{appName} if permission is denied for /etc |

etc.packageJson([dir]) ⇒ object

Read package.json [1] of current project or [2] from any other location. If relative path is supplied for dir such as package.json or node-etc/package.json(=node-etc), the file will we looked for in [1] the cwd path moving down one level till it is found, [2] in /etc/${appName}, [3] in ~/etc/${appName}, [4] {projectRoot}/etc, [5] {projectRoot}/.etc, [6] {projectRoot}/config, [7] {projectRoot}/config

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

| Param | Type | Default | Description | | --- | --- | --- | --- | | [dir] | string | "'package.json'" | Either absolute or relative path, with/without package.json at the end. |

etc.projectRoot() ⇒ string

Get the root dir of current project by locating package.json

Kind: instance method of etc
Returns: string - - project root directory

etc.parseJSON(filePath) ⇒ object

Read json file

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

| Param | Type | Description | | --- | --- | --- | | filePath | string | relative or absolute path of file to read. If relative path is supplied for dir such as package.json or node-etc/package.json(=node-etc), the file will we looked for in [1] the cwd path moving down one level till it is found, [2] in /etc/${appName}, [3] in ~/etc/${appName}, [4] {projectRoot}/etc, [5] {projectRoot}/.etc, [6] {projectRoot}/config, [7] {projectRoot}/config |

etc.argv() ⇒ object

return command line arguments

Kind: instance method of etc
Returns: object - - Returns object containing command line arguments

etc.directory(dir) ⇒ object

read configuration from .yaml/.yml, .env and json files in given directory.

Kind: instance method of etc

| Param | Type | Description | | --- | --- | --- | | dir | string | absolute path of directory |

etc.parseYAML([filePath]) ⇒ object

Read yaml file

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

| Param | Type | Default | Description | | --- | --- | --- | --- | | [filePath] | string | "'conf'" | relative or absolute path of file to read, with either .yaml/.yml extension or without. If argument supplied is file.yaml, but file.yml is found instead, file.yml will be returned. If relative path is supplied for filePath such as config.yaml or node-etc/config.yaml(=node-etc/config), the file will we looked for in [1] the cwd path moving down one level till it is found, [2] in /etc/${appName}, [3] in ~/etc/${appName}, [4] {projectRoot}/etc, [5] {projectRoot}/.etc, [6] {projectRoot}/config, [7] {projectRoot}/config |

etc.env([dir]) ⇒ object

Loads environment variables from a .env file in either [1] current project or [2] from any other location and returns process.env. If dir is not supplied, the function moves up the directories in the cwd path and returns the first .env file found. If absolute path is not given for dir, it also loads .env from /etc/{dir}. If dir is not given, it is taken as the program name as contained in the package.json file in the root directory of the project.

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

| Param | Type | Default | Description | | --- | --- | --- | --- | | [dir] | string | "''" | directory name from which to read .env file. Can be either a directory name or absolute path of directory |

etc.getFilePath(configType, fileName)

Get filepath if file with given name exists in: [1] the cwd path moving down one level till it is found [2] /etc/${appName} [3] ~/etc/${appName} [4] {projectRoot}/etc [5] {projectRoot}/.etc [6] {projectRoot}/config [7] {projectRoot}/config

Kind: instance method of etc

| Param | Type | | --- | --- | | configType | 'json' | 'yaml' | 'yml' | 'env' | | fileName | string |

etc.readConfigData(configType, filePath, config)

readConfiguration of configType from given path

Kind: instance method of etc

| Param | Type | Description | | --- | --- | --- | | configType | 'json' | 'yaml' | 'yml' | 'env' | | | filePath | string | filename with/without extension/ absolute path | | config | object | |

etc.addConfig(configType, filePath, config)

Add new values to config/modify existing ones

Kind: instance method of etc

| Param | Type | Description | | --- | --- | --- | | configType | 'json' | 'yaml' | 'yml' | 'env' | | | filePath | string | filename with/without extension/ absolute path | | config | object | |

etc.deleteConfig(configType, filePath, config)

Delete values from config

Kind: instance method of etc

| Param | Type | Description | | --- | --- | --- | | configType | 'json' | 'yaml' | 'yml' | 'env' | | | filePath | string | filename with/without extension/ absolute path | | config | array | fields to remove |

etc.editConfig(configType, filePath, config)

Add new values to config/modify existing ones

Kind: instance method of etc

| Param | Type | Description | | --- | --- | --- | | configType | 'json' | 'yaml' | 'yml' | 'env' | | | filePath | string | filename with/without extension/ absolute path | | config | object | |

etc.save(configType, filePath, config)

Save config values

Kind: instance method of etc

| Param | Type | Description | | --- | --- | --- | | configType | 'json' | 'yaml' | 'yml' | 'env' | | | filePath | string | absolute path | | config | array | fields to save |

etc.all()

Load all configurations

Kind: instance method of etc

Credits

Inspired by cpsubrian/node-etc

Developed by CSECO

CSECO is a mechatronics firm specializing in engineering technology to be cheap enough to be affordable to low income earners.

http://www.cseco.co.ke