The following files are looked up and merged (the latest take precedence):

Usage no npm install needed!

<script type="module">
  import appConf from '';



Package Version Build Status PackagePhobia Latest Commit


The following files are looked up and merged (the latest take precedence):

  1. vendor: config.* in the application directory;
  2. global: /etc/my-application/config.*;
  3. user: ~/.config/my-application/config.*;
  4. local: /.my-application.* down to ./.my-application.* in the current working directory;

Note: the local config is relative to the current working directory and only makes sense for CLIs.

var loadConfig = require("app-conf").load;

loadConfig("my-application", {
  // this is the directory where the vendor conf is stored
  // vendor config will not be loaded if not defined
  appDir: __dirname,

  // default config values
  defaults: {},

  // which types of config should be loaded
  entries: ["vendor", "global", "user", "local"],

  // whether to ignore unknown file formats instead of throwing
  ignoreUnknownFormats: false,
}).then(function (config) {

Relative paths, string values starting by ./ or ../, are automatically resolved from the config file directory.

Paths relative to the home directory, string values starting by ~/, are also automatically resolved.

JSON format is supported natively but you may install the following packages to have additional features:

watch(opts, cb)

This method reload the configuration every time it might have changed.

const watchConfig = require("app-conf").watch;

const stopWatching = await watchConfig(
    // contrary to `load`, this is part of the options
    appName: "my-application",

    // all other options are passed to load()
  (error, config) => {
    if (error !== undefined) {
      console.warn("loading config has failed");

      // we might not want to retry on changes


    console.log("config has been loaded", config);


A basic CLI is available to show the config:

> ./node_modules/.bin/app-conf
Usage: app-conf <appName> [<appDir>]

app-conf v1.0.0
> ./node_modules/.bin/app-conf my-app .

Note: To ensure the configuration is parsed the same way as your application (e.g. optional formats), this command should be run from your appliacation directory and not from a global install.


Contributions are very welcome, either on the documentation or on the code.

You may:

  • report any issue you've encountered;
  • fork and create a pull request.


ISC © Julien Fontanet