Application configuration: DRY, flexible and type-safe. Pick any three.
This project is deprecated and no longer maintained.
Configa was originally factored out of another project, Sparkla, and intended to be a library for application configuration using TypeScript and JSON Schema. We envisaged that it would be reused for our CLI tools such as Encoda and Executa.
However, at the time of writing, we have focussed on developing command line and configuration management interfaces using Rust in the main Stencila repo (and keeping TypeScript CLIs very simple). Much of the functionality of Configa is provided by the Rust crates structopt
and validate
. There are probably TypeScript analogues to those if you prefer that as a development environment.
npm install --save @stencila/configa
Configa uses Typescript classes to define configuration options. Create a file config.ts
with a single class defining your application configuration e.g.
import { minimum, maximum } from '@stencila/configa/dist/define'
/**
* myapp ${version}: ${description}
*/
export class Config {
/**
* An option that can be a boolean of a string
*/
optionA: boolean | string = 'default-value'
/**
* An option that is not required but has additional validations
*/
@minimum(1)
@maximum(10)
optionA?: number
}
Generate the JSON Schema that will be used at run time to validate and document your application's options:
configa schema
import { collectConfig, helpUsage } from '@stencila/configa/dist/run'
// App config as Typescript for compile time type-checking
import { Config } from './config'
// App config as JSON Schema for run time type-checking and help generation
import configSchema from './config.schema.json'
// Generate a typed configuration object
const { args = [], config } = collectConfig<Config>('myapp', configSchema)
// Generate help from the JSON Schema
if (args.includes('help')) console.log(helpUsage(configSchema))
In your README.md
add comments to indicate where to insert documentation e.g.
<\!-- CONFIGA-TABLE-BEGIN -->
<\!-- CONFIGA-TABLE-END -->
Then run,
configa readme
All configuration options can be set, in descending order of priority, by:
- a command line argument e.g.
--<value> <value>
- an environment variable prefixed with
CONFIGA_
e.g.CONFIGA_<option>=<value>
- a
.json
or.ini
configuration file, set using the--config
option, or.configarc
by default
Name | Description | Type | Validators | Default |
---|---|---|---|---|
appName | The name of the application.1 | string |
undefined |
|
configPath | Path to the configuration file to be parsed.2 | string |
undefined |
|
jsonSchemaPath | Path to the JSON Schema file to be generated.3 | string |
undefined |
|
readmePath | Path to the README file to be updated. | string |
"README.md" |
- Determines the expected prefix on the names of
config files and environment variables.
If
undefined
then parse the name from the package name in./package.json
. - If
undefined
, then will search for a fileconfig.ts
in the current directory and its subdirectories. - If
undefined
, then will be the path of the config file with extension.json.schema
instead of.ts
.