tessl/npm-nconf
Hierarchical node.js configuration with files, environment variables, command-line arguments, and atomic object merging
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-nconf@0.13.0index.mddocs/
nconf
nconf is a hierarchical node.js configuration library that provides unified access to configuration data from multiple sources including files, environment variables, command-line arguments, and static values. It uses a priority-based hierarchy system where configuration sources can be arranged in order of precedence, enabling flexible configuration management for Node.js applications.
Package Information
- Package Name: nconf
- Package Type: npm
- Language: JavaScript
- Installation:
npm install nconf
Core Imports
const nconf = require('nconf');For ES modules:
import nconf from 'nconf';Basic Usage
const nconf = require('nconf');
// Setup configuration hierarchy (order matters - first has highest priority)
nconf
.argv() // 1. Command-line arguments
.env() // 2. Environment variables
.file({ file: './config.json' }); // 3. Configuration file
// Set configuration values
nconf.set('database:host', 'localhost');
nconf.set('database:port', 5432);
// Get configuration values
const dbHost = nconf.get('database:host');
const dbPort = nconf.get('database:port');
const dbConfig = nconf.get('database'); // Gets entire object
// Save configuration to file
nconf.save((err) => {
if (err) console.error('Error saving config:', err);
});Architecture
nconf is built around several key components:
- Provider: Main configuration manager that orchestrates multiple stores
- Store System: Pluggable storage backends (Memory, File, Argv, Env, Literal)
- Hierarchical Access: Priority-ordered configuration sources with fallback behavior
- Key Namespacing: Colon-delimited nested key support (
'database:host') - Atomic Operations: Consistent read/write operations across all stores
- Format Support: JSON and INI file formats with extensible parsing
Capabilities
Configuration Management
Core configuration operations for getting, setting, and managing hierarchical configuration data with support for nested keys and multiple data sources.
/**
* Retrieve configuration value for the specified key
* @param {string} key - Configuration key (supports nested keys with ':' delimiter)
* @param {function} [callback] - Optional callback for async operation
* @returns {*} Configuration value or undefined if not found
*/
get(key, callback);
/**
* Set configuration value for the specified key
* @param {string} key - Configuration key (supports nested keys with ':' delimiter)
* @param {*} value - Value to set
* @param {function} [callback] - Optional callback for async operation
* @returns {Provider} Provider instance for chaining
*/
set(key, value, callback);
/**
* Remove configuration key and its value
* @param {string} key - Configuration key to remove
* @param {function} [callback] - Optional callback for async operation
* @returns {Provider} Provider instance for chaining
*/
clear(key, callback);
/**
* Merge object into existing configuration at key
* @param {string} [key] - Target key, or merge into root if not provided
* @param {Object} value - Object to merge
* @param {function} [callback] - Optional callback for async operation
* @returns {Provider} Provider instance for chaining
*/
merge(key, value, callback);Store Management
Store management system for adding, removing, and configuring different configuration sources with priority-based hierarchical access.
/**
* Add a configuration store to the hierarchy
* @param {string} name - Store name
* @param {Object} options - Store configuration options
* @param {string} [usage] - Usage information for argv store
* @returns {Provider} Provider instance for chaining
*/
add(name, options, usage);
/**
* Remove a store from the hierarchy
* @param {string} name - Store name to remove
* @returns {Provider} Provider instance for chaining
*/
remove(name);
/**
* Add or replace a store (idempotent operation)
* @param {string} name - Store name
* @param {Object} options - Store configuration options
* @returns {Provider} Provider instance for chaining
*/
use(name, options);File Operations
File-based configuration with support for JSON and INI formats, encrypted storage, and automatic file discovery with search functionality.
/**
* Add file store to configuration hierarchy
* @param {string|Object} key - Store name or file path, or options object
* @param {string|Object} [options] - File path or options object
* @returns {Provider} Provider instance for chaining
*/
file(key, options);
/**
* Load configuration from all stores
* @param {function} [callback] - Optional callback for async operation
* @returns {Object|Promise} Configuration object
*/
load(callback);
/**
* Save configuration to all stores
* @param {*} [value] - Optional value to save
* @param {function} [callback] - Optional callback for async operation
* @returns {Object|Promise} Saved configuration data
*/
save(value, callback);Command Line and Environment
Integration with command-line arguments via yargs and environment variables with filtering, transformation, and parsing capabilities.
/**
* Add command-line arguments store to hierarchy
* @param {Object} [options] - yargs options or yargs instance
* @returns {Provider} Provider instance for chaining
*/
argv(options);
/**
* Add environment variables store to hierarchy
* @param {Object|Array|string} [options] - Environment variable options, whitelist array, or separator
* @returns {Provider} Provider instance for chaining
*/
env(options);Utilities and Validation
Utility functions for key manipulation, file loading, object merging, and configuration validation with required key checking.
/**
* Validate that required configuration keys are present
* @param {string[]} keys - Array of required key names
* @throws {Error} If any required keys are missing
* @returns {boolean} True if all keys are present
*/
required(keys);
/**
* Get first truthy value from a list of keys
* @param {string[]|...string} keys - Array of keys or variable arguments
* @param {function} [callback] - Optional callback for async operation
* @returns {*} First truthy value found
*/
any(keys, callback);
/**
* Clear all configuration data
* @param {function} [callback] - Optional callback for async operation
* @returns {Provider} Provider instance for chaining
*/
reset(callback);Static Properties and Methods
/**
* Package version string
*/
nconf.version: string;
/**
* Provider constructor for creating multiple instances
*/
nconf.Provider: Function;
/**
* Store constructor classes
*/
nconf.Argv: Function;
nconf.Env: Function;
nconf.File: Function;
nconf.Literal: Function;
nconf.Memory: Function;
/**
* Utility functions available on main nconf object
*/
nconf.key(...args): string;
nconf.path(key, separator): string[];
nconf.keyed(separator, ...args): string;
nconf.loadFiles(files, callback): void;
nconf.loadFilesSync(files): Object;
nconf.parseValues(value): any;
nconf.transform(map, fn): Object;
nconf.formats: Object;Types
/**
* Main configuration provider class
*/
class Provider {
constructor(options);
stores: Object; // Active configuration stores
sources: Array; // Read-only configuration sources
}
/**
* Provider constructor options
*/
interface ProviderOptions {
type?: string; // Single store type to initialize
store?: StoreOptions; // Single store configuration
stores?: Object; // Multiple store configurations
source?: SourceOptions; // Single read-only source
sources?: Object; // Multiple read-only sources
}
/**
* Available store types
*/
const StoreTypes = {
Memory: 'memory', // In-memory configuration store
File: 'file', // File-based configuration store
Argv: 'argv', // Command-line arguments store
Env: 'env', // Environment variables store
Literal: 'literal' // Static object store
};
/**
* Configuration formats
*/
const Formats = {
json: {
parse: Function, // JSON.parse
stringify: Function // JSON.stringify with formatting
},
ini: {
parse: Function, // INI format parser
stringify: Function // INI format stringifier
}
};