Use node-config to create configuration files in Node.js

Managing multiple configuration files across different environments can be challenging, and there are multiple tools that are trying to solve this problem in different ways. However, in this article, we will learn how to use node-config create and manage Node.js configuration files across different deployment environments.

What is node-config?

Node-config allows you to create configuration files for different deployment environments in your Node application. With it, you can define a default configuration file that you intend to reuse across environments, and then extend the default configuration to other environments such as development, staging, etc.

You can override these parameters with some temporary command line parameters, such as adding NODE_ENV=development your command line parameters.

Node-config makes it easier to create and manage a consistent configuration interface that is shared across all deployment environments.

To better understand how to set this configuration, let's use a sample Node application. First, clone this repository by running the command below on your terminal, or download and unzip it from here.

git clone https://github.com/ezesundayeze/node-env-sample

To install Node dependencies, run:

npm install

set-node-config

Because node-config is an npm package, we can install it with npm or yarn by running any of these commands.

npm install config

or

yarn add config

Supported node-config file extensions

Node-config supports many file extensions. At the time of publication, the current version of node-config (3.3.6) supports the following extensions:

- .json
- .json5
- .hjson
- .yaml or .yml
- .coffee
- .js
- .cson
- .properties
- .toml
- .ts
- .xml

This means that you can create your config file with any of the supported extensions, but it makes sense to choose an extension for your project and stick with it throughout the build process.

In this tutorial, we will use the .json extension.

Create default environment variables

Create a config directory and add a config/default.json file to it. This will be the default configuration file and will contain all default environment variables.

In our sample application it should look like this:

config/default.json

{
  "server": {
    "host": "localhost",
    "port": 0,
  }
}

We will access it in our application by importing config and using the get method to access the variable.

const config = require('config');
const port = config.get('server.port');
const host = config.get('server.host');

Let's create a server.js file and add the following code.

const express = require('express');
const config = require('config');
const app = express();
const port = config.get('server.port');
const host = config.get('server.host');

app.get('/', (req, res) => {
  res.send('Hello World');
});
const server = app.listen(port, host, (err) => {
  if (err) {
    console.log(err);
    process.exit(1);
  }
  console.log(`Server is running on ${host}:${server.address().port}`);
});

You can use node-config in a similar way in other parts of your application.

Extended default configuration file

You can extend the default configuration file by creating additional configuration files. For example, you can create profiles for development, production, QA, staging, local, etc. Let's walk through the main types of configuration files that we will use in our application.

local configuration file

A local configuration file is created to override the deployed version of your configuration file. For example, for your development deployment, you can have a local-development.json file to store all your local development configuration - it reflects the kind of behavior you would expect in the deployed development environment.

So you can have something like this:

local-{instance}.EXT
local-{deployment}.EXT
local-{deployment}-{instance}.EXT

Short hostname and full hostname

You can also use the short and full hostname to define your profile on a specific platform, in case you are deploying on multiple instances. For example, you can have a {short_hostname} which will represent your server name until the first dot. If your hostname is demo.example.com , the configuration can be demo.EXT (demo.json) .

Also, if your {full_hostname} is your entire server name, you can {short_hostname} conflicts with other machines. So in the case where your hostname is demo.example.com , your profile name would be demo.example.com.json .

custom configuration file

You may also want to create a custom configuration file to accommodate some environment variable overrides. Node-config provides support for configuration file types that you can define with the name custom-environment-variables.EXT（custom-environment-variables.json）

Test configuration values

If your environment variables are not set, services that use them will break. So, you should make sure your environment variables are tested. Node-config provides several utilities, one of which is the config.has() method, which allows you to verify that environment variables are set.

You can create a test file or add it to your pre-commit hook to make sure your config files are all set up.

Here is an example of how to check for the existence of a configuration variable config.has()

if (config.has('dbConfig')) { 
... 
}

You can also use it in your Jest tests like this:

const config = require('config');
test('Server config exist', () => {
  expect(config.has("server")).toBe(true);
});
test('Default config exist', () => {
  expect(config.has("server.port")).toBe(true);
  expect(config.has("server.host")).toBe(true);
});

Rewrite using the command line

Using command line overrides allows you to specify configuration parameters on the fly from your terminal or command line. NODE_CONFIG='{...}' command when starting the application. The parameters must be in JSON string format.

Below is an example:

NODE_CONFIG='{"server": {"host":"192.168.43.13", "port":"3030"}}' npm run dev

Single quotes around JSON values allow you to use double quotes safely. In some cases, depending on your operating system, you may need to escape certain characters. You can also use command line export to avoid typing commands all the time.

Running the command below on your terminal will override your server's host and port or any other configuration you choose to override.

export NODE_CONFIG='{"server": {"host":"192.168.43.13", "port":"3030"}}'

If you prefer to use JavaScript, you can add it to your server file before calling the configuration library, like this:

const express = require('express');
process.env.NODE_CONFIG = '{"server": {"host":"localhost", "port":"3030"}}';
const config = require('config');

The trick is to set the NODE_CONFIG variable to a JSON string before the config is loaded.

This happens because command line overrides take precedence over all other types of overrides. Below are some reserved words that cannot be used as environment variables when using node-config, because the library provides their implementation and may conflict with yours.

get
has
util
getConfigSources
makeHidden
makeImmutable
setModuleDefaults
watch 
_attachProtoDeep
_cloneDeep
_diffDeep

This is not an exhaustive list, so be sure to check the documentation.

There are some plug-ins allow you to efficiently use node-config and Docker to manage keys, a plug-in that lets you automatically reload node-config (you probably already know, the configuration file will not change automatically when loaded), and allows you to 161dff12e3b291 uncache your config variable.

Summarize

When using node-config, there are countless ways to configure your Node application. With it, you can easily manage your configuration files and extend them as needed for maximum flexibility, reliability and consistency in your projects. thanks for reading.