user-conf

Manage configs in the user home directory

Made with ❤ at @outlandish

Easily persist and update a JSON object in a user's home directory.

Simplifies managing a single configuration (JSON) object for Node programs that need to save user options, e.g. CLI apps. Probably has other uses too but CLI apps is why I made this.

Install

npm install --save user-conf

yarn add user-conf

Import

// ES2015
import UserConf from 'user-conf'

// CommonJS
var userConf = require('user-conf')

Usage

userConf.init(name[, baseOptions]) : UserConfig

Initialise or get a user configuration.

The first time this is run the configuration is initialised with the baseOptions object.

• name {String} name of the config
• base {Object} (optional) base config object (default: {})

Returns an instance of UserConfig (available at exports.UserConfig).

API

All methods except destroy have a *Sync equivalent, e.g. getSync() and setSync().

UserConfig#get([key, cb]) : *

Get all options or one option by passing key.

• key {String} (optional) key name of option, accepts dot-paths
• cb {Function} (optional) error-first callback

UserConfig#set([key,] val[, cb])

Set an option value or the whole object (pass val as first argument)

• key {String} (optional) key name of option, accepts dot-paths
• value {*} value of option (must be serialisable as JSON)
• cb {Function} (optional) error-first callback

UserConfig#update(diff[, cb])

Merge an object into the user configuration.

• diff {Object} options object to merge (must be serialisable as JSON)
• cb {Function} (optional) error-first callback

UserConfig#clear([cb])

Clear the user configuration object of all options.

• cb {Function} (optional) error-first callback

UserConfig#destroy([cb])

Delete the config from filesystem.

• cb {Function} (optional) error-first callback

Example

import userConf from 'user-conf'
import prompt from 'inquirer'

const conf = userConf.init('user-name-app', {name: 'Joe Bloggs'})

console.log(conf.getSync('name')) 
//=> first run: "Joe Bloggs" 
//=> subsequent runs: "Spongebob Squarepants" 

prompt([{name: 'What\'s your name?'}]).then(({name}) => {
  conf.setSync('name', name)
  console.log(conf.getSync('name')) //=> "Spongebob Squarepants"
})

Contributing

All pull requests and issues welcome!

If you're not sure how, check out the great video tutorials on egghead.io!

License

MIT © Sam Gluck