Param variables

param variables read named parameters. Resolution checks CLI --param values first, then stage-specific params, then default params.


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

Use params when a value belongs to the config contract but should not be treated as a raw CLI option. This mirrors Serverless-style stage parameters and keeps reusable deployment inputs explicit.

Complete example

config.yml


stage: ${opt:stage, "dev"}
service: billing-api
 
domain: ${param:domain}
environmentName: ${param:environment}
 
database:
  host: ${param:dbHost}
  port: ${param:databasePort, 5432 | Number}
 
serviceUrl: https://${domain}/${stage}/${service}
 
stages:
  dev:
    params:
      domain: dev.example.test
      environment: development
      dbHost: localhost
  prod:
    params:
      domain: billing.example.com
      environment: production
      dbHost: prod-db.internal
  default:
    params:
      databasePort: 5432

Run it with a stage and any caller-supplied overrides:


configorama config.yml --stage prod --param domain=preview.example.com --param databasePort=6543

The CLI params win over stages.prod.params, and stages.default.params fills anything the selected stage does not define.


{
  "stage": "prod",
  "service": "billing-api",
  "domain": "preview.example.com",
  "environmentName": "production",
  "database": {
    "host": "prod-db.internal",
    "port": 6543
  },
  "serviceUrl": "https://preview.example.com/prod/billing-api"
}

The same input shape works through the API:

resolve.js


const configorama = require('configorama')
 
const config = await configorama('config.yml', {
  options: {
    stage: 'prod',
    param: [
      'domain=preview.example.com',
      'databasePort=6543',
    ],
  },
})

Lookup order

For ${param:name}, Configorama checks:

--param name=value or options.param
stages.<stage>.params.name
stages.default.params.name
legacy params.<stage>.name
legacy params.default.name
the fallback in the variable, such as ${param:name, "fallback"}

See variable sources for source classes and dynamic configuration for stage-driven examples.