Nautilus: Pelagic Mollusc
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



    Configuration-loader utility for Node.js to load different set of configuration files depending on your execution environment.

    Simply prepare your configuration files and call require('app-config'). Available configurations and environments are determined dynamically, based on your directory and file structures.


    In Java environment, classpath is used to 'inject' paths of right configuration files.

    In Javascript world, there is nothing like classpath. This tool is here to solve your multi-environment configuration problem.

    Quick intro to usage

    Create database config file for dev environment


    Give the config file some content

    module.exports = {
        hostname: 'localhost',
        port: 1234

    Load the config in your app

    var config = require('app-config');
    console.log('DB URL:', config.db.hostname + ':' + config.db.port);

    Run your app

    NODE_ENV=dev node you_app.js

    Like it? Read on for more details.

    Directory structure

    An example of directory structure required by the tool.


    Each environment is a separate directory of the same name. In the example above, we have two environments: dev and prod. Configuration files are stored within each environment directory. Any sub-directory under an environment directory will be ignored.

    Configuration files located directly under config/ directory are supported for two reasons:

    • They are loaded in case no execution environment is set
    • Allow you to use a build tool (Grunt for example) to assemble the right config files in the root of config/ directory depending on which environment you are building a package for.
      • For example, for production packages, you may want to copy only the .js files of config/prod/ into the package's config/ directory

    Configuration files' format

    Javascript-only files are supported and they must export an object. Example config/prod/log.js:

    module.exports = {
        emitErrors: true,
        fileLogConfig: {
            filename: '/var/log/app.log',
            level: 'debug'


    When calling require('app-config'), configuration files are loaded depending on the execution environment, which is being set by using environmental variables. More on that below.

    Returned object upon require call for the example directory structure:

        log: {
            emitErrors: true,
            fileLogConfig: {
                filename: '/var/log/app.log',
                level: 'debug'
        db: {

    Example usage in a Node.js module

    var config = require('app-config');
    console.log('Log level:', config.log.fileLogConfig.level);

    Configuration options

    All configuration options are available via the environment variables below. Some examples of how to set the environmental variables:

    • NODE_ENV=dev NODE_CONFIG_NO_HALT= node index.js
    • NODE_ENV=qa NODE_CONFIG_DIR='/qa/config/path/' node index.js
    • NODE_ENV=prod NODE_CONFIG_LOG= NODE_CONFIG_DIR='/prod/config/path/' node index.js


    Environment to be used when requiring the tool. In our example, we have dev and prod.


    Configuration directory is expected to be called 'config' and to be located in the root of your app/project. You can change this default behavior by setting this option up to whatever path you like.


    If an error occurs during the load of config files, the app is halted unless overridden by defining this option to whatever value. For example, the app is halted if the configuration directory does not exist, if an environment does not exist in config directory, etc.

    The app is being halted by executing process.exit(-1) command. If the halt is prevented by defining this option, the returned value by the require call is null and it is up to you to handle this situation.


    Prints out information and error messages into console if defined.

    Technical details

    This tool is fully synchronous. I.e. for all file operations, synchronous Node.js functions are being called. This is essential to have the config files loaded immediately upon require call. Since Node.js caches all require calls, this tool will be executed only ones ensuring no performance impact on the app.

    Code's logic insight

    The tool walks through config/ directory in your app's root (or any other provided directory via configuration) and scans for environment directory. When found, an object is returned, having properties of the same name as the log files - just the .js extension is stripped out.

    Object returned by require call on our example directory structure above with NODE_ENV=prod:

        db:  require(NODE_CONFIG_DIR + '/prod/db.js');
        log: require(NODE_CONFIG_DIR + '/prod/log.js');

    Prior requiring the db and log modules above, they are deleted from require.cache. This will ensure reloading of config files if you intentionally deleted app-config module from require.cache. Useful for unit testing when playing around with properties in object returned upon require('app-config').


    npm install app-config


    The tool does not depend on any other code. For developers of this tool, Mocha and Should are the only dependencies for running unit tests.


    In order to develop this plugin, these steps are required:

    • Clone the git repo by running git clone URL
    • Go to the newly created directory in Terminal
    • Run npm install to download dependencies
    • Run unit tests by npm test


    npm i app-config

    Downloadslast 7 days







    last publish


    • avatar