multiconf/README.md

Work with JSON configs

# Multiconf

[![NPM Downloads](https://img.shields.io/npm/dm/multiconf.svg)](https://npmjs.org/package/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

```bash
npm install multiconf
```

## Quick Start

```javascript
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');
```

## 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`:
```json
{
  "hostname": "localhost",
  "port": 3141,
  "token": "<default-token>"
}
```

`./conf/server.json`:
```json
{
  "hostname": "localhost",
  "port": 3141,
  "token": "QWERTY-123456"
}
```

## Usage

```javascript
// 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:

```jsonc
{
  // 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:

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

Set environment variables to override configurations:

```bash
# 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.

## License

MIT © 2017-2025 Volodymyr Sichka