Configorama

Configorama is a framework-agnostic resolver for dynamic configuration files. It reads YAML, JSON, TOML, INI, HCL, Markdown frontmatter, JavaScript, and TypeScript, then resolves variables from environment values, CLI options, files, git metadata, expressions, and custom sources. The docs are for people who need repeatable config behavior in local tools, CI jobs, deployment scripts, and agent workflows.

It exists because modern config rarely lives in one file anymore. A service config may depend on stage flags, secret environment variables, generated JavaScript, shared JSON files, and derived values. Configorama gives that flow one resolver, plus inspection modes that show what the config needs before you trust or execute it.

Install the package and resolve your first supercharged config file.

Getting started

Walk through required inputs from the config dependency graph.

Self configuring config

Inspect configs, collect required inputs, and resolve safely from automation.

For agents

Look up commands, API settings, schemas, sources, filters, and error codes.

API / CLI

Review required inputs, dependency graphs, audit findings, and debug output.

Introspection

Example

For example, given this simple yaml config file:


service: billing
stage: ${opt:stage, "dev"}

Running it through the CLI:


npm install configorama
configorama config.yml --stage prod

You get this resolved output:


{
  "service": "billing",
  "stage": "prod"
}

You can call the same resolver programmatically:

resolve-config.js


const configorama = require('configorama')
 
async function loadConfig() {
  const config = await configorama('config.yml', {
    options: {
      stage: 'prod'
    }
  })
 
  console.log(config)
}
 
loadConfig().catch(error => {
  console.error(error)
  process.exitCode = 1
})

How it works

The main paths through these docs are the first config guide, inspect config, for agents, bring your own syntax, the CLI reference, and the API reference. Read the architecture concept when you want the mental model behind the commands.