A useful library for handling configuration parameters

Usage no npm install needed!

<script type="module">
  import vConf from 'https://cdn.skypack.dev/v-conf';


bitHound Overall Score bitHound Dependencies TravisCI


An easy to use library for managing configuration parameters. V-conf was born inside the Volumio project and then has been migrated to a separate library.

The idea behind v-conf is to provide an easy way to manage configuration parameters. Main functionalities are:

  • Configuration parameters can be organized in a hierarchy
  • Optionally store data on file
  • Data is automatically saved after a configurable amount of time
  • Data write is reduced by delaying disk writes
  • Callbacks can be associated to configuration keys.


To install it include the library in your package.json as follows (replacing VERSION with latest version number)

    "name": "test",
    "version": "1",
    "dependencies": {
        "v-conf": "VERSION"

and then run

npm install

In your package.json pick latest version if you don't need a specific one.

If you want to install the library manually run the following command on the root of your project

npm install v-conf

or install v-conf globally

npm install -g v-conf



V-conf needs to be instantiated somewhere in your code.

var config=new (require('v-conf'))();

Then you can decide whether creating your data structure manually or load it from disk. A configuration value can be added as follows:


Instead a configuration file can be loaded by executing


If you load the configuration from file you automatically activate the autosave option. This option saves the updated configuration after a configured amount of time. This allows grouping write option thus saving your SD card (in case you run the code on a device like a Raspberry PI)

Key structure

As shown by the addConfigValue example above the configuration values are organized in a tree structure. This allows grouping of data. The method addConfigValue automatically creates the missing structures for you.

The following code


creates an internal representation like the following


Data types

Supported types are: boolean, string, number, array



Adds a configuration key to the structure.

  • key: the key for the configuration values you're about to add. If key is an array don't provide any index, item is added at the end of the array
  • type: one of the supported data types
  • value: the current value



or config.addConfigValue('groupa.configuration','array',false);


Updates the value of the key. If the key doesn't exists, the method creates it inferring the value type.

  • key: the key of an existing configuration values. If item is an array, provide the index.
  • value: the value to set


config.set('groupa.configuration.items[1]','my string');


Retrieves the current value for the specified key.

  • key: the key of an existing configuration values

Returns the value associated to the key or undefined


var values=config.get('groupa.configuration');


Deletes the configuration parameter specified by the key.

  • key: the key of an existing configuration values




This method checks the existence of a key

  • key: the key to check

Returns eturns true or false depending on the existence of a key in the configuration file


var exists=config.has('groupa.configuration');    


Lists all the children keys of the specified one.

  • key: the key of an existing configuration values


var keys=config.getKeys('groupa.configuration');

registerCallback(key, callback)

Register a callback function to be executed when the value is updated

  • key: the key of an existing configuration values that you want to be notified of its value change
  • callback: a callback function that will be invoked when the value is updated. The new value is passed to the function.


                            console.log('NEW VALUE: '+data);