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
• 🚀 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.

License

MIT © 2017-2026 Volodymyr Sichka