Using nconf to configure a Node.js application


Sometimes things vary from environment to environment. Like, how we wear a tie to the office, but would try not to elsewhere, save for a few occasions. Similarly, in Node.js, you might want configuration settings to change in each environment. Some of these settings include IP address, port number, database configurations etc., that change from the development to production environment. The recommended approach for changing your app’s environment is by using the NODE_ENV environment variable.

Currently, Node.js does not have a standard way of managing config variables, but luckily there are a number of node modules that will help you to standardize this. One among them is the nconf package. Nconf provides a hierarchical Node.js configuration with files, command-line arguments, and environment variables.

Storing local configuration data

The simplest approach for storing the configuration for a Node.js app generally involves having an object stored as a JSON on the file system. This can be easily done using the JSON.parse and JSON.stringify methods.

Let’s look at this simple example:

Saving Data

Accessing the saved data

This works well for smaller applications, but as your application grows and runs on multiple environments, you’ll have to account for:

  1. Different values for different configuration options based on the environment (production, staging and dev).
  2. Configuration object getting too large, or configuration structure becoming too unwieldy.

Let’s see how nconf will make work easier and the code less prone to error.

What can we do using nconf?

  1. Standard configurations can be kept in a separate file so that you can edit them without affecting the code.
  2. We can grab the environment variables and arguments to the script using built-in functions like nconf.env() and nconf.argv().
  3. Configurations can be accessed using standard JavaScript object syntax.
  4. Able to specify a different configuration file on the command line, so that you can easily switch between various configurations on different server environments.

Using nconf



Let’s consider the above example and see how we can access configuration settings from the config.json using nconf.

While reading the configuration settings from JSON file, you can directly specify config file path or a different configuration file on the command line itself, like below.

** Make sure that you don’t commit production configuration to your version control since it contains credentials that you want only certain people to view.

In the above example, reading configuration settings from JSON file can be written as below.

Setting up a hierarchy of different sources

Managing configuration settings can get complicated if we are using different settings on our production environment.

Using nconf, you can set up a hierarchy for different sources of your configuration. The order in which they’re used will specify which options override the other. In our application, we had followed the below order:
file < env < argv
The rightmost one has the highest priority (in this case argv). The file here is config.json that holds the configuration settings, env is environmental variables and argv  is command line arguments that we pass.

Here’s one example to see how the hierarchy works.

  1. Defining HTTP port in config.json.
  2. Reading HTTP port from different sources using nconf.
  3. Now, set environmental variable for the port as 3001 without passing command line arguments and run your application using npm start. Notice that your server runs on 3001 port.
  4. Next, run your application with the command npm start -- --http:port=3000 and you can notice that your server runs on 3000 port.
  5. Finally, run your application again but without passing any command line argument and without setting the environmental variable. You’ll notice that your server runs on port 8000 which is passed via the configuration file.

Notice that we are first reading config files (.file()), then the environment variables (.env()) and then the command line arguments (.argv()). The config items that were loaded later will override any previous item, so feel free to re-order them as you want.


Nconf is a simple node module that provides us a robust way to get configuration information into our Node.js apps. It collects data from the host environment, command line arguments, and even multiple configuration files through a simple interface. This allows developers and admins to configure their application in any way they want based on the environment.

Posted By: Sindhusha B, Osmosee

Are you interested? follow us and get notified of new posts

One thought on “Using nconf to configure a Node.js application

  1. hiteshlala
    at 1:34 am

    > “The config items that were loaded later will override any previous item ….”
    This is not what I found, when I tested earlier values took precedence.
    Eg. If my config.json is { test: ‘test’ } and I have process.env[‘test’] = ‘environment’.
    Then I do:
    nconf.env().file( ‘config.json’ );
    console.log( nconf.get( ‘test’ ) ); // outpus: environment

    but if I do:
    nconf.file( ‘config.json’ ).env();
    console.log( nconf.get( ‘test’ ) ); // outpus: test

Leave A Reply

3 × two =