Multiconf

A lightweight and flexible configuration management library for Node.js applications. Multiconf simplifies working with JSON and JSONC configuration files, supporting both user-defined and default configurations with environment variable overrides.

Features

• 📁 Simple JSON/JSONC configuration management
• 🔄 Automatic fallback to default configurations
• 💬 JSONC support (JSON with comments)
• 🌍 Environment variable overrides
• 🗂️ Multiple config directories with deep-merge
• 🎨 Optional template rendering of config values
• 🚀 Lightweight and zero-dependencies

Installation

npm install multiconf

Quick Start

const Multiconf = require('multiconf');

// Initialize with default config directory (./conf)
const conf = Multiconf.get();

// Or specify a custom config directory
const conf = Multiconf.get('./config');

// Or pass an array of directories — read in sequence and deep-merged
const conf = Multiconf.get(['./conf', './conf.local']);

Configuration Structure

Multiconf supports two types of configuration files:

1. User Configurations (*.json or *.jsonc)
2. Default Configurations (*.json.default or *.jsonc.default)

The library will first look for user configurations, falling back to default configurations if not found.

Example Configuration Files

./conf/server.json.default:

{
  "hostname": "localhost",
  "port": 3141,
  "token": "<default-token>"
}

./conf/server.json:

{
  "hostname": "localhost",
  "port": 3141,
  "token": "QWERTY-123456"
}

Usage

// Access configuration values
console.log(`${conf.server.hostname}:${conf.server.port}`); // "localhost:3141"
console.log(`Token is ${conf.server.token}`); // "Token is QWERTY-123456"

JSONC Support

Multiconf supports JSONC (JSON with comments) format:

{
  // Server configuration
  "hostname": "localhost", // Server hostname
  "port": 3141,            // Server port
  "token": "QWERTY-123456" // Authentication token
}

Note: JSONC files have higher priority than JSON files. If both server.jsonc and server.json exist, server.jsonc will be used.

Environment Variables

Override configuration values using environment variables:

// Initialize with environment variable prefix
const conf = Multiconf.get('./conf', 'APP_CONF_');

Set environment variables to override configurations:

# Override server configuration
APP_CONF_server='{"token":"env-token-12345"}'

Environment variables must contain valid JSON strings that will be parsed and merged into your configuration.

Multiple Config Directories

Both get() and getDefault() accept an array of directory paths. Directories are read in sequence and the resulting config objects are deep-merged, with later directories taking precedence over earlier ones.

const conf = Multiconf.get(['./conf', './conf.local']);

• Keys present only in an earlier directory are preserved.
• Keys present in a later directory overwrite earlier values.
• Nested plain objects are merged recursively — a conflicting sub-key does not wipe out sibling sub-keys.
• Arrays are treated as scalar values and are overwritten, not concatenated.

This is useful for layered configuration, such as shipping defaults in ./conf and allowing per-environment overrides in ./conf.local.

Directories can also be given as a single delimited string (default delimiter is ;), which is handy when directories come from a single environment variable:

const conf = Multiconf.get('./conf;./conf.local');

Use setDirDelimiter() to change the delimiter:

const conf = Multiconf.setDirDelimiter('|').get('./conf|./conf.local');

Template Rendering

Multiconf can render config values as templates, giving access to environment variables and the rest of the config object. It's disabled by default.

const conf = Multiconf.setTemplateRendering(true).get('./conf');

Template syntax:

{
  "greeting": "<%= env.USER_NAME %>",
  "combined": "<%= config.greeting %> and more",
  "encoded": "<%= to_base64('secret') %>"
}

• <%= expression %> — HTML-escaped interpolation
• <%- expression %> — raw interpolation
• <% code %> — execution without output
• env — process environment variables
• config — the config object being rendered
• to_base64 / from_base64 — base64 helper functions

Use setAllowedEnvVars() to restrict which environment variables are exposed to templates (accepts exact names and regular expressions; null allows all, which is the default):

Multiconf.setAllowedEnvVars(['API_KEY', /^DB_/]);

License

MIT © 2017-2026 Volodymyr Sichka