Dismiss
  • Scroll up
  • Toggle Theme
  • View as Mobile

David Wells

Builder of things

Software architect
& product wrangler

Software architect & product wrangler

Configorama

Configorama adds variable support to configuration files so environment-specific values can be composed without turning every config into custom JavaScript.

It is the kind of utility that comes from building repeatable systems: keep the config readable, make the dynamic parts explicit, and let the same structure work across local, staging, and production environments.

Why it matters

Infrastructure, deployment, and application config tends to drift when values are copied by hand. Variable-aware config keeps those moving parts easier to reuse and easier to review.

README excerpt

Key Features

  • Multiple file formats - yml, yaml, json, toml, ini, hcl (Terraform), TypeScript, JavaScript, markdown
  • Rich variable sources - env vars, CLI flags, file refs, git data, cron expressions, eval/if expressions
  • Async/sync function execution - Import and execute JavaScript/TypeScript files with argument passing
  • Self-referencing - Reference other values within the same config using dot notation
  • Custom variable sources - Pluggable architecture to add your own variable resolvers
  • Filters and functions - Transform and combine values with built-in or custom operators
  • Metadata extraction - Analyze configs without resolving them, or get full resolution history
  • Circular dependency detection - Helpful error messages instead of infinite loops
  • TypeScript support - Full type definitions and TypeScript file execution via tsx/ts-node

Getting Started

Installation

As a library dependency:

npm install configorama

As a global CLI tool:

npm install -g configorama

Quick Start

Async API (recommended for most use cases):

const path = require('path')
const configorama = require('configorama')
const cliFlags = require('minimist')(process.argv.slice(2))

// Path to yaml/json/toml config
const myConfigFilePath = path.join(__dirname, 'config.yml')

// Execute config resolution asynchronously
const config = await configorama(myConfigFilePath, { options: cliFlags })

console.log(config) // resolved config

Sync API (for synchronous execution contexts):

const path = require('path')
const configorama = require('configorama')
const cliFlags = require('minimist')(process.argv.slice(2))

// Path to yaml/json/toml config
const myConfigFilePath = path.join(__dirname, 'config.yml')

// Execute config resolution synchronously
const config = configorama.sync(myConfigFilePath, { options: cliFlags })

console.log(config) // resolved config

Example configuration file (config.yml):

# Environment variable
apiKey: ${env:API_KEY}

# CLI option (e.g., --stage prod)
environment: ${opt:stage, 'dev'}

# Self-reference to other values
service: my-app
fullName: ${service}-api

# File reference
secrets: ${file(./secrets.yml)}

# Git information
branch: ${git:branch}
commit: ${git:sha1}

# Conditional logic
memorySize: ${if(${environment} === 'prod' ? 1024 : 512)}

# Nested references
database:
  host: ${env:DB_HOST, 'localhost'}
  port: ${env:DB_PORT, 5432}
  name: ${service}-${environment}

Running Examples

The project includes example files demonstrating various features:

# Clone the repository
git clone https://github.com/DavidWells/configorama
cd configorama

# Install dependencies
npm install

# Run async API example
node examples/using-async-api.js --stage prod

# Run sync API example
node examples/using-sync-api.js --stage dev

# Run zero-config example
node examples/zero-config.js

# Run TypeScript example
node examples/typescript/using-typescript.js
configurationdeveloper-toolsautomation