Configa
Application configuration: DRY, flexible and type-safe. Pick any three.
⚠️ Configa is in early development. It's been factored out of Sparkla, another project in early development, for more general usage.
Install
npm install --save @stencila/configa
Quick start
1. Define a configuration class
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
}
2. Generate configuration schema
Generate the JSON Schema that will be used at run time to validate and document your application's options:
configa schema
3. Use your configuration in your application code
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))
4. Generate configuration documentation
In your README.md
add comments to indicate where to insert documentation e.g.
<\!-- CONFIGA-TABLE-BEGIN -->
<\!-- CONFIGA-TABLE-END -->
Then run,
configa readme
Usage
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
.