@atlex/config

Centralized configuration management with .env support and type-safe dot-notation access.

Installation

npm install @atlex/config
# or
yarn add @atlex/config

Quick Start

import { config, env, loadEnv } from '@atlex/config'

// Load environment variables from .env file
loadEnv()

// Access configuration with dot notation
const appName = config('app.name')
const dbHost = config('database.host')

// Get environment variables
const nodeEnv = env('NODE_ENV', 'development')

// Check if configuration exists
if (config.has('api.secret')) {
  const secret = config('api.secret')
}

// Get all configuration
const allConfig = config.all()

Features

• Dot-Notation Access: Access nested configuration using familiar dot notation syntax
• .env File Support: Automatically load environment variables from .env files
• Type-Safe Getters: Retrieve configuration with type coercion and default values
• Wildcard Queries: Query configuration hierarchies with wildcard patterns
• Configuration Caching: Cache configuration in memory for improved performance
• Environment Casting: Automatic type casting for environment variables
• File-Based Loaders: Load configuration from various file formats

Configuration Loading

Loading Environment Variables

import { loadEnv } from '@atlex/config'

// Load from .env file in the root directory
loadEnv()

// Load from a specific .env file
loadEnv('.env.local')

// Load from multiple files with precedence
loadEnv('.env')
loadEnv('.env.local') // Overrides .env values

Checking Environment Variables

import { hasEnv, envs } from '@atlex/config'

// Check if an environment variable exists
if (hasEnv('DATABASE_URL')) {
  console.log('Database is configured')
}

// Get all environment variables as an object
const allEnvs = envs()
console.log(allEnvs)

ConfigRepository API

Dot-Notation Access

import { config } from '@atlex/config'

// Get single value with dot notation
const appName: string = config('app.name')
const dbHost: string = config('database.host')
const dbPort: number = config('database.port')

// Get with default value
const apiTimeout = config('api.timeout', 30000)

// Get with type coercion
const debugMode = config.string('app.debug') // Converts to string
const maxConnections = config.integer('database.maxConnections')
const enableCache = config.boolean('cache.enabled')

Checking Configuration

import { config } from '@atlex/config'

// Check if a configuration key exists
if (config.has('api.key')) {
  console.log('API key is configured')
}

// Check multiple keys
const hasAllRequired = config.has('database.host', 'database.name')

Wildcard Queries

import { config } from '@atlex/config'

// Get all database configuration
const dbConfig = config('database.*')
// Returns: { host: 'localhost', port: 5432, name: 'myapp' }

// Get all values at any depth
const allMailSettings = config('mail.**')

Setting Configuration

import { config } from '@atlex/config'

// Set a configuration value at runtime
config.set('api.timeout', 60000)

// Set nested values
config.set('database', {
  host: 'localhost',
  port: 5432,
  name: 'production_db',
})

// Set multiple values
config.set({
  'app.name': 'My App',
  'app.version': '1.0.0',
  debug: false,
})

Getting All Configuration

import { config } from '@atlex/config'

// Get entire configuration object
const allConfig = config.all()

// Merge with additional values
const merged = {
  ...config.all(),
  runtime: {
    startTime: Date.now(),
  },
}

Environment Casting

import { EnvCaster } from '@atlex/config'

const caster = new EnvCaster()

// Cast to string
const appName = caster.asString('APP_NAME')

// Cast to integer
const port = caster.asInteger('PORT', 3000)

// Cast to boolean
const debug = caster.asBoolean('DEBUG')

// Cast to array (comma-separated or custom)
const allowedHosts = caster.asArray('ALLOWED_HOSTS', 'localhost,127.0.0.1')

// Cast to JSON
const dbPool = caster.asJson('DB_POOL', { min: 2, max: 10 })

File-Based Configuration

Using FileConfigLoader

import { FileConfigLoader } from '@atlex/config'
import path from 'path'

const loader = new FileConfigLoader(path.join(__dirname, '../config'))

// Load all .js or .ts files from config directory
const appConfig = loader.load('app') // Loads app.js/app.ts
const databaseConfig = loader.load('database') // Loads database.js/database.ts
const mailConfig = loader.load('mail') // Loads mail.js/mail.ts

// Example config file structure:
// config/app.ts
export default {
  name: process.env.APP_NAME || 'Atlex App',
  environment: process.env.NODE_ENV || 'development',
  debug: process.env.APP_DEBUG === 'true',
  url: process.env.APP_URL || 'http://localhost:3000',
}

Configuration Caching

import { readCachedConfigSync, writeConfigCacheSync, clearConfigCacheSync } from '@atlex/config'

// Read from cache (returns null if not cached)
const cached = readCachedConfigSync()
if (cached) {
  console.log('Using cached configuration')
}

// Write configuration to cache
import { config } from '@atlex/config'
writeConfigCacheSync(config.all())

// Clear cache
clearConfigCacheSync()

Complete Example

import { config, env, loadEnv } from '@atlex/config'
import { FileConfigLoader } from '@atlex/config'
import path from 'path'

// 1. Load environment variables
loadEnv()

// 2. Load configuration files
const loader = new FileConfigLoader(path.join(__dirname, '../config'))

// 3. Set up configuration structure
config.set({
  app: {
    name: loader.load('app').name,
    environment: env('NODE_ENV', 'development'),
    debug: env('APP_DEBUG') === 'true',
  },
  database: {
    host: env('DB_HOST', 'localhost'),
    port: env('DB_PORT', 5432),
    name: env('DB_NAME', 'atlex'),
    user: env('DB_USER'),
    password: env('DB_PASSWORD'),
  },
  api: {
    timeout: env.integer('API_TIMEOUT', 30000),
    retries: env.integer('API_RETRIES', 3),
  },
})

// 4. Use configuration throughout your app
console.log(`Running ${config('app.name')} in ${config('app.environment')} mode`)

if (config('app.debug')) {
  console.log('Debug mode is enabled')
}

const dbPool = {
  host: config('database.host'),
  port: config('database.port'),
  database: config('database.name'),
  user: config('database.user'),
  password: config('database.password'),
}

console.log('Database configured:', dbPool)

API Overview

ConfigRepository

Method	Description
get(key, defaultValue?)	Get configuration value with dot notation
set(key, value)	Set configuration value(s)
has(...keys)	Check if configuration key(s) exist
all()	Get entire configuration object
string(key, defaultValue?)	Get value as string
integer(key, defaultValue?)	Get value as integer
boolean(key, defaultValue?)	Get value as boolean
array(key, defaultValue?)	Get value as array

EnvCaster

Method	Description
asString(key, defaultValue?)	Cast environment variable to string
asInteger(key, defaultValue?)	Cast environment variable to integer
asBoolean(key, defaultValue?)	Cast environment variable to boolean
asArray(key, defaultValue?)	Cast environment variable to array
asJson(key, defaultValue?)	Cast environment variable to JSON object

Helper Functions

Function	Description
config(key, defaultValue?)	Get configuration value (same as ConfigRepository.get)
env(key, defaultValue?)	Get environment variable
envs()	Get all environment variables
hasEnv(key)	Check if environment variable exists
loadEnv(file?)	Load environment variables from .env file
readCachedConfigSync()	Read cached configuration
writeConfigCacheSync(config)	Write configuration to cache
clearConfigCacheSync()	Clear configuration cache

Configuration

Environment Variables

Variable	Description	Default
NODE_ENV	Application environment	development
APP_DEBUG	Enable debug mode	false
CONFIG_CACHE	Enable configuration caching	false

.env File Format

# Application
APP_NAME="My Application"
APP_DEBUG=true
APP_URL=http://localhost:3000

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp_db
DB_USER=postgres
DB_PASSWORD=secret

# API
API_TIMEOUT=30000
API_RETRIES=3

# Feature Flags
FEATURE_NEW_DASHBOARD=true
FEATURE_BETA_API=false

Documentation

For complete documentation, visit https://atlex.dev/guide/config

License

MIT

Part of Atlex — A modern framework for Node.js.