Configuration builder in NodeJS with TypeScript

In recent project that I am working on we had a requirement of creating a configuration builder that satisfies following requirements:

  • Ability to read default configuration from a file
  • Ability to read environment specific configuration from a file
  • Ability to override any defaults by command line options
  • Ability to override and/or access any defaults by the set as environment variables
  • Ability to update configuration by any module in the application without modifying default configuration module
  • Ability to read configuration from the database

Some background

The application in which this configuration builder needs to be developed follows a modular approach where each logically grouped functionalities are defined in a module and registers themselves to the main application. A similar approach to that of Angular 1.x modules. Each module receives application object while core app is going through module registration code, so the module can access any application properties that are public. The application is developed in NodeJS and the language of code that we are using TypeScript, so we had the ability to write classes, interfaces, and decorators to simplify code and make it more maintainable.

To put in simple words, we wanted a configuration module which can read arguments, environment variables, configuration files, and database while at the same time provide the ability to any other module in application to easily access and update configuration if required. Other modules will mostly add their configuration options into default config object, at application startup, so other places it can be accessed.

Making configuration builder


To start with, I created default configuration class, which will do the default configuration read and hold the result in itself. This will then be attached to main Application object as the configuration of the application, every update to configuration will alter this class only.

export default class AppConfig implements IConfig {
    additionalConfigs: Types.Map;

    constructor() {
        this.additionalConfigs = {};

    putExtra(key: string, value: any, override?: boolean): boolean {
        if (this.additionalConfigs[key] && !override) {
            return false;
        this.additionalConfigs[key] = value;
        return true;

    getExtra(key: string): any {
        return this.additionalConfigs[key];

IConfig is an interface where I define how default configuration is going to look like. The additionalConfigs and related extra methods were added just in case someone decides not to populate default configuration space and want to add it in additional space then they can use it while updating configuration object.

Once default configuration structure is ready, I defined an interface called IConfigurationBuilder with a method called buildConfiguration that accepts an AppConfig object as an argument. The idea behind this is that if any module wants to contribute in configuration building activity then they can implement this interface, register itself to ConfiurationBuilder and rest will be handled by the builder to make sure that it’s buildConfiguration is executed while configuration was being built.

export interface IConfigBuilder {
    configure(config: AppConfig): Promise<any>;

After that, I defined a ConfigurationBuilder, which is responsible for building configuration on application startup by following all above requirements. It will first read default configuration and initialise AppConfig instance, then reads environment files and update configuration object, then read command line options and environment variables and add them to configuration object and finally go through different ConfigurationBuilders registered by different modules and call their buildConfiguration method which updates configuration object based on their requirement. Some default configuration builders we implemented are EnvAndOptConfigReader and DatabaseConfigReader.

export default class ConfigBuilder {
    private builders: Array<IConfigBuilder>;
    private config: AppConfig;

    constructor(configFilePath?: string) { = [];
        if (!configFilePath && fs.existsSync("config.json")) {
            configFilePath = path.join(process.cwd(), "config.json");
        this.config = new AppConfig();
        const customConfig = require(configFilePath);
        _.merge(this.config, customConfig);

    addConfigBuilder(builder: IConfigBuilder): ConfigBuilder {;
        return this;

    build(): Promise<any> {
        let defers: Array<Promise<any>> = []; IConfigBuilder) => {
        return Promise.all(defers).then(() => {
            return this.config;

As you can see in the constructor it reads default config.JSON file and initialise AppConfig with it. The `addConfigBuilder` method is supposed to be used by other modules to register their ConfigurationBuilders and finally `build` method loops over all registered builders and waits for them to finish updating configuration object by using deferred promise.


Following are some advantages of this:

  • Clean and maintainable code
  • Easy to understand
  • Easy to extend – to add new configuration for a specific module is easy and does not require to update core code
  • Isolation

What else can be done?

In addition to this to make it easier, decorators can be added to the system which will auto-register your class to the builder. Same way decorators for other facilities can also be added like environment specific class loading. To do this you can either use some available auto-discovery plugin for typescript or implement a custom solution using metadata features of a decorator.

Do not reinvent wheel

Search for an available solution before implementing your own, there are some good solutions available online which can do similar stuff. The available solution at this point of time was not sufficient to cover all our application related structure and requirements which led to defining custom solution but for you, you might be able to find readily available solution in NPM repository.

Final note

Above code is just for illustration purpose and not production ready, you need to tweak it and add more validations/checks to make it more suitable for production.

%d bloggers like this: