# @stencila/configa

> Application configuration: DRY, flexible and type-safe

Latest version **0.4.8** (published 2020-05-22) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @stencila/configa
pnpm add @stencila/configa
yarn add @stencila/configa
bun add @stencila/configa
```

Provides the command `configa`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.4.8 |
| Published | 2020-05-22 |
| First published | 2019-11-27 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 80.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Stencila |
| Maintainers | ketch, nokome, stencila-ci |
| Keywords | configuration |

## Links

- npm: https://www.npmjs.com/package/@stencila/configa
- Repository: https://github.com/stencila/configa
- Homepage: https://github.com/stencila/configa#readme
- Issues: https://github.com/stencila/configa/issues
- npm.io page: https://npm.io/package/@stencila/configa

## Dependencies (7)

- [rc](https://npm.io/package/rc.md) ^1.2.8
- [ajv](https://npm.io/package/ajv.md) ^6.12.2
- [chalk](https://npm.io/package/chalk.md) ^4.0.0
- [json5](https://npm.io/package/json5.md) ^2.1.2
- [globby](https://npm.io/package/globby.md) ^11.0.0
- [typedoc](https://npm.io/package/typedoc.md) ^0.17.7
- [@stencila/logga](https://npm.io/package/@stencila/logga.md) ^2.2.0

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.4.8 (latest) — 2020-05-22
- 0.4.7 — 2020-03-23
- 0.4.6 — 2020-03-16
- 0.4.5 — 2020-03-02
- 0.4.4 — 2020-02-26
- 0.4.3 — 2020-02-24
- 0.4.2 — 2020-01-09
- 0.4.1 — 2020-01-09
- 0.4.0 — 2019-12-17
- 0.3.0 — 2019-12-04
- 0.2.1 — 2019-12-02
- 0.2.0 — 2019-12-02
- 0.1.0 — 2019-11-27

## README

# Configa

> Application configuration: DRY, flexible and type-safe. Pick any three.

[![Build status](https://travis-ci.org/stencila/configa.svg?branch=master)](https://travis-ci.org/stencila/configa)
[![Code coverage](https://codecov.io/gh/stencila/configa/branch/master/graph/badge.svg)](https://codecov.io/gh/stencila/configa)
[![NPM](https://img.shields.io/npm/v/@stencila/configa.svg?style=flat)](https://www.npmjs.com/package/@stencila/configa)

> :warning: Configa is in early development. It's been factored out of [Sparkla](https://github.com/stencila/sparkla), another project in early development, for more general usage.

## Install

```bash
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.

```ts
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:

```bash
configa schema
```

### 3. Use your configuration in your application code

```ts
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.

```md
<\!-- CONFIGA-TABLE-BEGIN -->
<\!-- CONFIGA-TABLE-END -->
```

Then run,

```bash
configa readme
```

## Usage

<!-- prettier-ignore-start -->
<!-- CONFIGA-USAGE-BEGIN -->
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
<!-- CONFIGA-USAGE-END -->

<!-- CONFIGA-TABLE-BEGIN -->
| Name           | Description                                                                                     | Type     | Validators | Default       |
| -------------- | ----------------------------------------------------------------------------------------------- | -------- | ---------- | ------------- |
| appName        | The name of the application.<a href="#appName-details"><sup>1</sup></a>                         | `string` |            | `undefined`   |
| configPath     | Path to the configuration file to be parsed.<a href="#configPath-details"><sup>2</sup></a>      | `string` |            | `undefined`   |
| jsonSchemaPath | Path to the JSON Schema file to be generated.<a href="#jsonSchemaPath-details"><sup>3</sup></a> | `string` |            | `undefined`   |
| readmePath     | Path to the README file to be updated.                                                          | `string` |            | `"README.md"` |


1. <a id="appName-details"></a>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`.
2. <a id="configPath-details"></a>If `undefined`, then will search for a file
`config.ts` in the current directory and its
subdirectories.
3. <a id="jsonSchemaPath-details"></a>If `undefined`, then will be the path of the
config file with extension `.json.schema` instead of
`.ts`.

<!-- CONFIGA-TABLE-END -->
<!-- prettier-ignore-end -->

---
_Source: https://npm.io/package/@stencila/configa · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._