Variable sources

Variable sources describe where each dynamic value comes from. Use this page when you want the syntax for each built-in source in one place, then open the per-variable pages when you need edge cases or policy details.

The source system is fully customizable: add your own variable sources when config values need to come from an internal service, secret store, deployment registry, or any project-specific lookup.


stage: ${opt:stage, "dev"}
secret: ${env:API_KEY}
branch: ${git:branch, "main"}
fileData: ${file(./config.json):key}

Source	Syntax	Source class	Notes
Environment	`${env:NAME}`	`user`	Reads `process.env`.
Options	`${opt:name}` or `${option:name}`	`user`	Reads CLI/API options.
Params	`${param:name}`	`user`	Reads named parameters.
Self	`${self:path}` or `${path}`	`config`	Reads the current config object.
File	`${file(./path.yml)}`	`config`	Reads and parses a local file.
Text	`${text(./script.txt)}`	`config`	Reads raw text.
Git	`${git:branch}`	`readonly`	Spawns git commands.
Cron	`${cron(...)}`	`readonly`	Converts readable schedules to cron strings.
Eval	`${eval(...)}`	`readonly` data-flow	Evaluates sandboxed expressions.
If	`${if(...)}`	`readonly` data-flow	Chooses values with sandboxed conditions.

opt: and option: are aliases for CLI/API options. param: is a separate named parameter source, which is useful when a config has stage params or caller-supplied values that should not be confused with raw CLI flags.

Environment

Use env for values supplied by the process environment. Add a fallback when local development can proceed without the variable.


apiHost: ${env:DOCS_API_HOST, "localhost"}
apiPort: ${env:DOCS_API_PORT, 3000 | Number}

See environment variables.

Options

Use opt or option for invocation-specific CLI flags or API options values.


stage: ${opt:stage, "dev"}
region: ${option:region, "us-east-1"}

See option variables.

Params

Use param for named parameters that belong to the config contract but should not be treated as raw CLI flags.


domain: ${param:domain, "example.test"}
databasePort: ${param:databasePort, 5432 | Number}

See param variables.

Self

Use self for values already present in the current config object. Bare paths can also resolve as self references when they match config values.


service: billing
stage: ${opt:stage, "dev"}
baseUrl: https://${self:apiHost}:${self:apiPort}
serviceUrl: ${baseUrl}/${stage}/${service}

See self variables.

File

Use file(...) to import another local file. You can read the whole parsed file or select a nested property.


settings: ${file(./settings.yml)}
databaseHost: ${file(./settings.yml):database.host}
databasePortFromFile: ${file(./settings.yml).database.port}

See file variables.

Text

Use text(...) when you need raw file contents instead of parsed YAML, JSON, TOML, or another structured format.


template: ${text(./message.txt)}

See text variables.

Git

Use git for readonly repository metadata. Add fallbacks when the config may resolve outside a git checkout.


branchName: ${git:branch, "main"}
shortSha: ${git:sha1, "unknown"}

See git variables.

Cron

Use cron(...) to convert readable schedules into cron expressions.


everyFiveMinutes: ${cron(every 5 minutes)}
weekdayMorning: ${cron(on monday at 9:00)}

See cron variables.

Eval

Use eval(...) for small sandboxed expressions against resolved config data.


replicas: ${opt:replicas, 2 | Number}
isScaled: ${eval(${self:replicas} > 1)}

See eval variables.

If

Use if(...) for readable conditional choices.


provider:
  stage: ${opt:stage, "dev"}
environmentName: '${if(provider.stage === "prod") ? "production" : "development"}'
workerCount: '${if(provider.stage === "prod") ? 4 : 1}'

See if variables.

Custom sources

Custom sources can match by prefix, regex, or function and can expose metadata for downstream inspection. Treat them as executable extensions in safe mode because the resolver function is user-provided code.

resolve-config.js


const configorama = require('configorama')
 
const config = await configorama('config.yml', {
  variableSources: [
    {
      type: 'secret',
      source: 'remote',
      prefix: 'secret',
      match: /^secret:/,
      resolver: async variable => {
        const key = variable.replace(/^secret:/, '')
        return readSecretFromStore(key)
      }
    }
  ]
})

config.yml


apiKey: ${secret:payments/api-key}

See write a custom variable source, security model, and filters and functions.