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
- 🗂️ Multiple config directories with deep-merge
- 🎨 Optional template rendering of config values
- 🚀 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');

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

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

```js
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:

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

Use `setDirDelimiter()` to change the delimiter:

```js
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.

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

Template syntax:

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

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

## License

MIT © 2017-2026 Volodymyr Sichka