Use JS, TS, and ESM config

Executable config files are useful when static data files are not expressive enough. This guide is for teams that already trust the repository and want config modules that can export objects, functions, or async functions while still letting Configorama resolve variable strings inside the returned value.

The feature exists because some projects need shared constants, package-local helpers, or computed defaults. The tradeoff is important: loading JavaScript, TypeScript, or ESM runs code. Treat executable config as trusted source code, and use audit or safe inspection before automation reads unknown repositories.

If the dynamic part is just a config-time decision, use eval variables instead. eval(...) handles comparisons, arithmetic, boolean checks, and ternaries without loading executable code.

module.exports = ({ options = {} } = {}) => ({
  service: 'billing',
  stage: options.stage || '${opt:stage, "dev"}',
  host: '${env:API_HOST, "localhost"}'
})

export default {
  service: 'billing',
  stage: '${opt:stage, "dev"}',
  workers: '${opt:workers, 2 | Number}'
}

export default async function config() {
  return {
    service: 'billing',
    stage: '${opt:stage, "dev"}'
  }
}

configorama config.ts --stage prod --workers 4

The same trust rule applies to ${file(./value.js)} and ${file(./value.ts)} references. Pure data file references are covered in file references, while blocked execution behavior is covered in safe inspection. For API options such as dynamicArgs, see the API reference.