@strata-js/util-env-config

Environment Config

EnvConfig is a configuration manager with support for many scenarios of configuration. It was designed with the idea of being able to be used for development (or with file-based configuration) very easily, while also supporting more advanced configuration management at the same time.

This project is under the Strata.js family, because this type of configuration is most commonly needed by services, and it is included as a part of @stratajs/strata. However, sometimes, there are projects that don't use Strata, but might need configuration to be handled in the same way. (A good example of this is Strata Service Tools.) It's for these projects that this exists.

Installation

This middleware package is published via GitLab's npm repository. It is not (currently) available on the public npm repo. It is, however, hosted in the same way as Strata.js itself, and since Strata.js is a prerequisite for this package, you should already be good to go. (If not, please see the Installation section here.)

Simply do:

// npm
$ npm add @stratajs/env-config

// yarn
$ yarn add @stratajs/env-config

Usage

Loading configuration

There are two methods for loading a configuration into the configuration manager: setConfig and parseConfig. While the names may be similar, they do two very different things. Both are exposed to cover all possible use cases.

setConfig(config : Record<string, unknown>) : void

The setConfig function is as simple as it gets. It takes a configuration, and it sets it. There is nothing special about the configuration, except that it conform to the type Record<string, unknown>.

parseConfig(config : Record<string, unknown>) : void

The parseConfig function is where the magic happens. This function supports several very handy shortcuts, which require we parse the configuration file in order to build the correct configuration. Once that config is built, we call setConfig ourselves.

Environment-based configurations

The first thing parseConfig looks for, is a configuration object that has an environments key. (This is not required, but it is one of the two major reasons to use parseConfig.) What it then does is to look for the ENVIRONMENT or NODE_ENVIRONMENT variable, and then apply any configuration found under environments[ENVIRONMENT].

Let's look at an example. Given the following configuration:

// config.ts
export default {
    http: {
        secure: false,
        port: 12345
    },
    
    environments: {
        test: {
            http: {
                secure: true
            }
        },
        production: {
            http: {
                secure: true,
                port: 443
            }
        }
    }
}

Then the following will be true:

import config from './config.ts';
import configMan from '@stratajs/env-config'

//---------------------------------------

// Set our environment to 'local'
process.env.ENVIRONMENT = 'local';
configMan.parseConfig(config);

// { secure: false, port: 12345 }
console.log(configMan.get('http'));

//---------------------------------------

// Set our environment to 'test'
process.env.ENVIRONMENT = 'test';
configMan.parseConfig(config);

// { secure: true, port: 12345 }
console.log(configMan.get('http'));

//---------------------------------------

// Set our environment to 'production'
process.env.ENVIRONMENT = 'production';
configMan.parseConfig(config);

// { secure: true, port: 443 }
console.log(configMan.get('http'));

This allows one configuration file to contain the details about multiple environments, while reusing most of the default configuration. If an environment isn't specified, the default configuration is used.

Environment Variable config overriding

The other feature of parseConfig is support for overriding sections of config with environment variables. It looks for any environment variables that start with CONFIG., and then replaces the values of the config at that location with the value of the environment variable. In order to handle conversions from the traditional UPPERCASE of environment variables, we are passing this to lodash's camelCase function. This should be sufficient for most use cases.

WARNING: Due to the nature of environment variables, the type for any overridden property is string.

Let's look at an example. Give the configuration:

// config.ts
export default {
    http: {
        secure: false,
        port: 12345
    },
    
    environments: {
        test: {
            http: {
                secure: true
            }
        },
        production: {
            http: {
                secure: true,
                port: 443
            }
        }
    }
}

Then the following will be true:

import config from './config.ts';
import configMan from '@stratajs/env-config'

//---------------------------------------

// Override our default config
process.env.CONFIG.HTTP.PORT = '4545';
configMan.parseConfig(config);

// { secure: false, port: 4545 }
console.log(configMan.get('http'));

//---------------------------------------

// We support mixing both types of configuration
process.env.ENVIRONMENT = 'test';
process.env.CONFIG.HTTP.PORT = '4545';
configMan.parseConfig(config);

// { secure: true, port: 4545 }
console.log(configMan.get('http'));

//---------------------------------------

// The environment variables take precedence over the environment configurations.
process.env.ENVIRONMENT = 'production';
process.env.CONFIG.HTTP.PORT = '4545';
configMan.parseConfig(config);

// { secure: true, port: 4545 }
console.log(configMan.get('http'));

Loading from an external source

Because of how the configuration manager is written, it's trivial to load the configuration from an external source. Here are a few examples:

import axios from 'axios';
import configUtil from '@stratajs/env-config'

//---------------------------------------

// Local config file
configUtil.parseConfig(await import('./config.ts'));

// HTTP call
const { data } = await $http.get('https://example.com/config/production.json');
configUtil.setConfig(JSON.parse(data));