or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async-config.mdconfig-utilities.mdcore-config.mddeferred-config.mdenvironment-integration.mdindex.mdraw-config.md
tile.json

tessl/npm-config

Configuration control for production node deployments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/config@4.1.x

To install, run

npx @tessl/cli install tessl/npm-config@4.1.0

index.mddocs/

Config

Config is a comprehensive configuration management library for Node.js applications that enables hierarchical configurations across different deployment environments. It supports multiple configuration file formats, environment variable overrides, command line parameters, and provides a consistent interface for accessing configuration values with validation and type safety.

Package Information

  • Package Name: config
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install config

Core Imports

const config = require('config');

For ES modules (if supported):

import config from 'config';

Access to additional modules:

const { asyncConfig, resolveAsyncConfigs } = require('config/async');
const { deferConfig } = require('config/defer');
const { raw } = require('config/raw');

Basic Usage

const config = require('config');

// Get configuration values
const dbHost = config.get('database.host');
const dbPort = config.get('database.port');

// Check if configuration exists
if (config.has('cache.enabled')) {
  const cacheEnabled = config.get('cache.enabled');
}

// Access nested configuration
const serverConfig = config.get('server');
console.log(`Server: ${serverConfig.host}:${serverConfig.port}`);

// Direct property access (also available)
const appName = config.appName;

Architecture

Config is built around several key components:

  • Configuration Hierarchy: Loads configuration files in order of precedence (default → environment → hostname → local)
  • Environment Integration: Supports NODE_ENV-based configuration loading and environment variable overrides
  • File Format Support: Handles JSON, YAML, HJSON, JSON5, CSON, TOML, Properties, JavaScript, TypeScript, CoffeeScript, and XML files
  • Immutability System: Makes configurations immutable after first access to prevent runtime modifications
  • Utility Namespace: Comprehensive utilities for configuration management, file loading, and object manipulation
  • Extension Modules: Additional modules for async configurations, deferred loading, and raw object handling

Capabilities

Core Configuration Access

Primary interface for accessing configuration values with validation and type safety. Provides get/has methods and direct property access.

/**
 * Get configuration value by property path
 * @param property - Dot-notation path to configuration property
 * @returns Configuration value
 * @throws Error if property is undefined
 */
config.get(property: string): any;

/**
 * Test if configuration property exists
 * @param property - Dot-notation path to configuration property  
 * @returns True if property exists, false otherwise
 */
config.has(property: string): boolean;

Core Configuration

Configuration Utilities

Comprehensive utilities for configuration management, including module defaults, immutability control, file loading, and object manipulation.

// Module defaults
config.util.setModuleDefaults(moduleName: string, defaultProperties: object): object;

// Immutability control
config.util.makeImmutable(object: object, property?: string | string[], value?: any): object;
config.util.makeHidden(object: object, property: string, value?: any): object;

// Configuration sources and loading
config.util.getConfigSources(): ConfigSource[];
config.util.loadFileConfigs(configDir?: string, options?: LoadOptions): object;

Configuration Utilities

Async Configuration

Support for asynchronous configuration loading with promise-based resolution and deferred initialization.

/**
 * Create async configuration value
 * @param promiseOrFunc - Promise or function returning promise
 * @returns Async configuration object
 */
function asyncConfig(promiseOrFunc: Promise | Function): AsyncConfig;

/**
 * Resolve all async configurations
 * @param config - Configuration object containing async values
 * @returns Promise resolving to completed configuration
 */
function resolveAsyncConfigs(config: object): Promise<object>;

Async Configuration

Deferred Configuration

Lazy-loading configuration values that are computed on first access using provided functions.

/**
 * Create deferred configuration value
 * @param func - Function to compute value on first access
 * @returns Deferred configuration object
 */
function deferConfig(func: Function): DeferredConfig;

Deferred Configuration

Raw Configuration

Protection for configuration objects that should remain unmodified by the config system.

/**
 * Wrap object to prevent config system modifications
 * @param rawObj - Object to protect from modifications
 * @returns Raw configuration wrapper
 */
function raw(rawObj: object): RawConfig;

Raw Configuration

Environment Integration

Comprehensive environment variable support, command line parameter handling, and multi-environment configuration loading.

Configuration file loading order:

  1. default.EXT
  2. {NODE_ENV}.EXT
  3. {hostname}.EXT
  4. {hostname}-{NODE_ENV}.EXT
  5. local.EXT
  6. local-{NODE_ENV}.EXT

Supported file extensions (EXT): js, ts, json, json5, jsonc, hjson, yaml, yml, coffee, iced, cson, properties, toml, xml

Environment Integration