v2.0.0 Is Live!

Visit the project's homepage for the latest version of this README.

---

wj-config

JavaScript configuration module for NodeJS and browser frameworks that works like ASP.net configuration where any number of data sources are merged and environment variables can contribute/overwrite values by following a naming convention.

Welcome to wj-config. This JavaScript configuration library works everywhere, most likely. The table below shows the frameworks or libraries that have successful samples in the examples folder in the left column. The right column is pretty much anything else out there that looks like it supports ES Modules.

Works With	Probably Works With
JavaScript  TypeScript  NodeJS  Deno  ReactJS  VueJS  Svelte	SolidJS  Preact  Electron  Angular  Remix  EmberJS  SennaJS  MithrilJS  SlingJS  Lit

Feel free to fork and pull request to include sample applications for your favorite library/framework.

Important Notes

1. This package has been written in TypeScript and transpiled to ES modules.
2. Building the configuration object is an asynchronous operation, so top level await is highly recommended.
3. The minimum supported NodeJS version is:

Features

In a nutshell, this configuration package provides:

• The ability to merge any number of data sources as one, just like ASP.net configuration loads files and memory dictionaries.
• 6 pre-defined data sources: JSON string, POJO object, single value, fetched data, dictionary, and environment.
• Condition the inclusion of a data source based on a predicate function's return value.
• Assign traits to the current environment and condition the inclusion of data sources based on the current environment's assigned traits.
• The ability to create special functions from data that is meant to be used to construct URL's. The created functions provide route replacement values, query string generation and URL encoding of replacement values.
• An environment object with the current environment definition and helpful isXXX() functions to quickly create conditionals based on the current environment, just like .Net's IHostEnvironment interface.
• Configuration value tracing: If needed for troubleshooting or debugging, the configuration builder will also create a full trace of all configuration values in the _trace property of the resulting configuration object.

Examples

There are working examples of use in GitHub here. Feel free to explore them and to contribute.

Technology	wj-config Version	Technology Version	Development Port
ReactJS	v1.0.2	ReactJS v18.2.0	3001
NodeJS Express	v1.0.2	Express v4.16.1	3002
ReactJS	v1.1.0	ReactJS v18.2.0	3003
NodeJS Console (CommonJS)	v2.0.0	v18.1.0
NodeJS Console (ES Modules)	v2.0.0	v18.1.0
NodeJS Express (CommonJS)	v2.0.0	Express v4.16.1	3004
NodeJS Express (ES Modules)	v2.0.0	Express v4.18.1	3005
ReactJS	v2.0.0	v18.2.0	3006
VueJS	v2.0.0	v3.2.45	3007
Deno	v2.0.0	v1.29.1
Svelte	v2.0.0	v3.54.0	3008

The repository contains the necessary launch.json file to run each of the examples in Visual Studio Code.

Quickstart

1. Install the NPM package.
2. Create your JSON configuration files (quickstart will assume you want per-environment configuration).
3. Build your configuration object.

1. Install the NPM Package

npm install wj-config

2. Create your JSON Configuration Files

Create a JSON file to be your main configuration file and name it, say config.json. For web projects you have two choices:

1. Include this file under the /src folder, in which case you later import it.
2. Include it in the /public or /static folder, in which case you later fetch it.

For NodeJS you import or load using the fs module.

Example configuration JSON:

{
    "app": {
        "title": "My Awesome App",
        "system": "awe-app",
        "id": "awe-app-appshell"
    },
    "logging": {
        "minLevel": "information"
    },
    "ws": {
        "defaultTimeout": 30,
        "gateway": {
            "rootPath": "/api/v1",
            "login": "/login",
            "catalogue": {
                "rootPath": "/cat",
                "getAll": "",
                "single": "/{catId}"
            }
        }
    }
}

NOTE: The ws section is special. See URL-Building Functions in the Wiki for the details.

Now write per-configuration JSON files. Example for development (would be named config.Development.json):

{
    "logging": {
        "minLevel": "debug"
    }
}

Yes, you only write the overrides, the values that change for the environment. All other configuration is still available, but does not have to be repeated.

3. Build Your Configuration Object

Create a module of yours called config.js or whatever pleases you. Obtain the environment name, load the 2 JSON files and build the configuration object. This is generally speaking.

There are two styles available: The classic style leaves to you, the programmer, the responsibility of figuring out a way to select the correct per-environment data source. The conditional style leaves the decision to the configuration builder. Pick whichever pleases you, but know that the latter is safer.

From now on, any code samples that call the loadJsonFile() function are referring to this one:

const loadJsonFile = (fileName, isRequired) => {
    const fileExists = fs.existsSync(fileName);
    if (fileExists) {
        const data = fs.readFileSync(fileName);
        return JSON.parse(data);
    }
    else if (isRequired) {
        throw new Error(`Configuration file ${fileName} is required but was not found.`);
    }
    // Return an empty object.
    return {};
};

If you don't like it, feel free to write your own. I wrote this like a year ago; I had no knowledge of the existence of the fs/promises module. If you write one yourself using async fs, please pull request and share the love. 😁😎

Classic Style

NodeJS ES Modules (Recommended)

import wjConfig, { Environment } from 'wj-config';
import mainConfig from "./config.json" assert {type: 'json'}; // Importing data is a thing in NodeJS.

// Obtain an environment object ahead of time to help setting configuration up.
const env = new Environment(process.env.NODE_ENV);

const configPromise = wjConfig()
    .addObject(mainConfig) // Main configuration JSON file.
    .name('Main') // Give data sources a meaningful name for value tracing purposes.
    .addObject(loadJsonFile(`./config.${env.current.name}.json`)) // The developer is deciding by using a file name tactic.
    .name(env.current.name)
    .addEnvironment(process.env) // Adds a data source that reads the environment variables in process.env.
    .includeEnvironment(env) // So the final configuration object has the environment property.
    .createUrlFunctions() // So the final configuration object will contain URL builder functions.
    .build(env.isDevelopment()); // Only trace configuration values in the Development environment.

// This is a top-level await:
export default await configPromise; // The build() function is asynchronous, so await its promise and export the result.

The calls to addEnvironment(), includeEnvironment() and createUrlFunctions() are not mandatory, they are just customary. Typically, you also want to include the environment variables, have the environment object and also make use of URL-Building Functions.

NodeJS CommonJS Modules (If You Must)

// Export the result of an IIFE, which will be a promise to return the configuration object.  This means that code in 
// need for the configuration object will have to execute inside async functions to be able to await, or wrap the 
// whole thing within a call to .then(), like in one of the examples provided in this project's repository.
// This is why CommonJS is discouraged.  It makes things more complex.
module.exports = (async function () {
    const { default: wjConfig, Environment } = await import('wj-config');
    const env = new Environment(process.env.NODE_ENV);
    return wjConfig()
        .addObject(loadJsonFile('./config.json', true))
        .name('Main')
        .addObject(loadJsonFile(`./config.${env.current.name}.json`))
        .name(env.current.name)
        .addEnvironment(process.env)
        .includeEnvironment(env)
        .createUrlFunctions()
        .build(env.isDevelopment());
})();

Web Projects

IMPORTANT: If your project is a React project creasted with Create React App, the recommendation is to eject or use the @craco/craco package (or similar one) in order to configure webpack to allow top-level awaits. You can read the details in the Top Level Await section in the Wiki. It can also work without top-level awaits, but in all honesty, I don't like it. The Wiki also explains how to achieve this for Vite projects (Vue, Svelte, React, etc.).

import wjConfig, { Environment } from 'wj-config';
import mainConfig from './config.json'; // One may import data like this, or fetch it.

const env = new Environment(window.env.REACT_ENVIRONMENT);
const configPromise = wjConfig()
    .addObject(mainConfig)
    .name('Main') // Give data sources a meaningful name for value tracing purposes.
    .addFetched(`/config.${env.current.name}.json`, false) // Fetch the JSON from the /public folder.
    .name(env.current.name)
    .addEnvironment(window.env, 'REACT_APP_') // Adds a data source that reads the environment variables in window.env.
    .includeEnvironment(env) // So the final configuration object has the environment property.
    .createUrlFunctions() // So the final configuration object will contain URL builder functions.
    .build(env.isDevelopment()); // Only trace configuration values in the Development environment.

export default await configPromise;

---

Ok, now go ahead and consume your configuration object anywhere you need it.

NodeJS ES Modules

import config from './config.js';

console.log(config.app.title);

NodeJS CommonJS Modules

const configPromise = require('./config.js');

configPromise.then(config => {
    console.log(config.app.title);
});

Web Projects

import config from './config';

console.log(config.app.title);

Conditional Style

Since v2.0.0

There are two possible ways to do conditional style per-environment configuration. The shortest first using the Web Projects sample:

import wjConfig, { Environment } from 'wj-config';
import mainConfig from './config.json';

const env = new Environment(window.env.REACT_ENVIRONMENT);
const config = wjConfig()
    .addObject(mainConfig)
    .name('Main')
    .includeEnvironment(env)
    .addPerEnvironment((b, envName) => b.addFetched(`/config.${envName}.json`, false))
    .addEnvironment(window.env, 'REACT_APP_')
    .createUrlFunctions()
    .build(env.isDevelopment());

export default await config;

It looks almost identical to the classic. This one has a few advantages:

1. Covers all possible environments.
2. Helps you avoid typos.
3. Makes sure there's at least one data source per defined environment.

IMPORTANT: This conditional style requires the call to includeEnvironment() and to be made before calling addPerEnvironment(). Make sure you define your environment names when creating the Environment object:

const env = new Environment(window.env.REACT_ENVIRONMENT, ['myDev', 'myTest', 'myProd']);

This way addPerEnvironment() knows your environment names.

The longer way of the conditional style looks like this:

import wjConfig, { Environment } from 'wj-config';
import mainConfig from './config.json';

const env = new Environment(window.env.REACT_ENVIRONMENT);
const config = wjConfig()
    .addObject(mainConfig)
    .name('Main')
    .addFetched(`/config.Development.json`, false)
    .forEnvironment('Development')
    .addFetched(`/config.PreProduction.json`, false)
    .forEnvironment('PreProduction')
    .addFetched(`/config.Production.json`, false)
    .forEnvironment('Production')
    .addEnvironment(window.env, 'REACT_APP_')
    .includeEnvironment(env)
    .createUrlFunctions()
    .build(env.isDevelopment());

export default await config;

This one has advantages 2 and 3 above, plus allows for the possiblity of having completely different data source types per environment. Furthermore, this allows you to add more environment-specific data sources if, for example, a particular environment requires 2 or more data sources. 95% of the time you'll need the short one only.

NOTE: This "long" version can be mixed with the "short" version, if you so desire.

This works in NodeJS too. There is a performance catch, though: If in NodeJS you use loadJsonFile() with the addObject() data source function, you'll be reading all per-environment configuration files, even the unqualified ones. To avoid this performance hit, pass a function to addObject() that, in turn, calls loadJsonFile():

import wjConfig, { Environment } from 'wj-config';
import mainConfig from "./config.json" assert {type: 'json'};

const env = new Environment(process.env.NODE_ENV);

const config = wjConfig()
    .addObject(mainConfig)
    .name('Main')
    .includeEnvironment(env)
    // Using a function that calls loadJsonFile() instead of calling loadJsonFile directly.
    .addPerEnvironment((b, envName) => b.addObject(() => loadJsonFile(`./config.${envName}.json`)))
    .addEnvironment(process.env)
    .createUrlFunctions()
    .build(env.isDevelopment());

export default await config;

Now you know how to do per-environment configuration in the classic and conditional styles. Pick your poison.

Documentation

This README was already too long, so all documentation has been re-written and placed in this repository's wiki. It is in English only for now; it should be available in Spanish too within the next few months.

Be sure to stop by because this not-so-quick start tutorial only scratched the surface of what is possible with wj-config.

Enjoy!