# @commenthol/dotconfig

> Config helper to (magically) override application settings with environment variables.

Latest version **1.5.3** (published 2024-11-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @commenthol/dotconfig
pnpm add @commenthol/dotconfig
yarn add @commenthol/dotconfig
bun add @commenthol/dotconfig
```

Provides the command `dotconfig`.

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.3 |
| Published | 2024-11-21 |
| First published | 2023-03-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 51.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | commenthol |
| Maintainers | commenthol |
| Keywords | dotenv, env, .env, environment, variables, config, settings, decryption |

## Links

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

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ^4.3.7
- [eciesjs](https://npm.io/package/eciesjs.md) ^0.4.12

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 1.5.3 (latest) — 2024-11-21
- 1.5.2 — 2024-11-18
- 1.5.1 — 2024-11-18
- 1.5.0 — 2024-08-10
- 1.4.0 — 2024-08-05
- 1.3.1 — 2024-08-05
- 1.3.0 — 2024-08-03
- 1.2.1 — 2024-08-03
- 1.2.0 — 2024-08-01
- 1.1.1 — 2024-02-01
- 1.1.0 — 2024-01-12
- 1.0.0 — 2023-08-14
- 0.2.1 — 2023-03-23
- 0.2.0 — 2023-03-20
- 0.1.2 — 2023-03-20
- … 1 more at https://npm.io/package/@commenthol/dotconfig/versions

## README

[![npm badge][npm-badge]][npm]
![types badge][types-badge]
![monthly downloads badge][npm-dm]

# dotconfig

Config helper to (magically) override application settings with environment
variables.

Comes packaged with a dotenv file loader.

Works with [dotenvx][] encrypted .env files and its .env.keys file. Uses same
[secp256k1](https://en.bitcoin.it/wiki/Secp256k1) encryption.

Comes bundled with a helper CLI to encryt and decrypt environment variables more
easily. See [Encryption](#encryption)

# Install

Add to your project:

```
npm i @commenthol/dotconfig
```

# Usage

File: `./config.js`

```js
import { dotconfig } from '@commenthol/dotconfig'

// loads process env vars from .env file and process env-vars
export const config = dotconfig({
  port: 8080,
  http: {
    proxy: undefined,
  },
  https: {
    cert: '',
    key: ''
  },
  sso: {
    serverUrl: 'https://my.sso',
    clientId: 'myClientId',
    clientSecret: undefined,
  },
  isProd: false,
  names: [], // arrays must be defined!
  user: {
    __group: true // groups env vars into object
                  // Here env-var MUST have min 3 parts with min 2 dashes!
  },
  // if loading from file default config var must contain at least `file://`
  loadFile: 'file://'
})
```

with file: `./.env`

```sh
export PORT=3000
export HTTP_PROXY=my-proxy:1234
export SSO_SERVER_URL=https://other.sso/path
export SSO_CLIENT_SECRET=ƚɘɿƆɘƧ
export NAMES_0=Alice
export NAMES_1=Bob
export NAMES_2=Charlie
export USER_0_USERNAME=Alice
export USER_0_PASSWORD="correct horse battery staple"
export USER_1_USERNAME=Bob
export USER_1_PASSWORD=ʇǝɹɔǝs
export IS_PROD=true
export ANY_OTHER_VALUE=1234
# Multi line values are supported (set them in quotes!)
export HTTPS_KEY="-----BEGIN PRIVATE KEY-----
MIIE...
-----END PRIVATE KEY-----"
export HTTPS_CERT='-----BEGIN CERTIFICATE-----
MIID...
-----END CERTIFICATE-----'
# loads content from file relative: `file://./relative` absolute: `file:///absolute`
export LOAD_FILE='file://./cert.key'
# use encrypted values together with a .env.keys file containing DOTENV_PRIVATE_KEY
DOTENV_PUBLIC_KEY="03d599cf2e4febf5e149ab727132117314a640e560f0d5c2395742e8219e9dbeee"
HELLO="encrypted:BOyGm1Oug6X4b+...wtJ2/j7+PtP1nThQ6YCw"
```

results in `config` being exported as

```js
const config = {
  http: {
    proxy: 'my-proxy:1234'
  },
  https: {
    key: '-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----',
    cert: '-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----'
  },
  port: 3000,
  sso: {
    serverUrl: 'https://other.sso/path',
    clientId: 'myClientId',
    clientSecret: 'ƚɘɿƆɘƧ'
  },
  names: ['Alice', 'Bob', 'Charlie'],
  user: {
    0: {
      username: 'Alice',
      password: 'correct horse battery staple'
    },
    1: {
      username: 'Bob',
      password: 'ʇǝɹɔǝs'
    }
  },
  isProd: true,
  anyOtherValue: '1234',
  // the content from `LOAD_FILE`
  loadFile: '-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----',
  // decrypted values nor private keys show up in `process.env` object
  hello: 'world'
}
```

<a id="encryption"> </a>

# Encryption

Can work with [dotenvx](https://dotenvx.com/docs/env-keys-file#encryption)
encrypted .env files for handling value encryption.

Comes bundled with own CLI to handle encryption of values in .env files:

```sh
# add package to your project first
npm i @commenthol/dotconfig
# get some help
npx dotconfig --help
# create a new .env file with encrypted value "foo"
npx dotconfig encrypt foo bar
# lookup decrypted value on stdout
npx dotconfig decrypt foo --stdout
```

ℹ️ **NOTE:** Never commit your `.env.keys` file. Keep it in a save place.

To use a different `.env.keys` file you may use DOTENV_PRIVATE_KEYS_PATH
env-var.

Decrypted values only appear in the config object but never in `process.env`.
Private keys are also only used internally for decryption and are deleted if
they appear in `process.env`.

# API

## dotconfig

dotconfig calls `dotenv.config()` first before passing the parsed `process.env`
variables through `getConfig()`.

<details>
<summary><i>Types</i></summary>

```ts
function dotconfig(
    /**
     * The default configuration object
     */
    defaultConfig: object, 
    /**
     * optional configuration options.
     */
    options?: DotConfigOptions
): Record<string, any> | {};

type DotConfigOptions = {
    /**
     * The path to the dotenv file. Default is '.env' in the current working 
     * directory. May be set via DOTENV_CONFIG_PATH env var.
     */
    path?: string | URL | undefined;
    /**
     * The encoding of the dotenv file. 
     * May be set via DOTENV_CONFIG_ENCODING env var.
     */
    encoding?: BufferEncoding | undefined;
    /**
     * Whether to override existing process environment variables. 
     * Default is false. May be set with DOTENV_CONFIG_OVERRIDE=true env var.
     */
    override?: boolean | undefined;
    /**
     * The process environment object to update. Default is `process.env`.
     */
    processEnv?: NodeJS.ProcessEnv | object;
    /**
     * if `false` do not add additional props on top-level not part of defaultConfig
     */
    additionalProps?: boolean | undefined;
    /**
     * if `false` do not add any additional props that are not part of defaultConfig
     */
    additionalPropsAll?: boolean | undefined;
    /**
     * default=true; Throw on decryption error
     */
    throwOnDecryptionError?: boolean | undefined;
};
```

</details>

## dotenv

dotenv comes with two methods `parse()` and `config()`.

`dotenv.config()` returns the parsed `.env` file (if found).

_Usage_

```js
import { dotenv } from '@commenthol/dotconfig'

// loads `.env` in current working directory
dotenv.config()

// loads `.env-local` relative to file
dotenv.config({
  path: new URL('./.env-local', import.meta.url)
})
```

<details>
<summary><i>Types</i></summary>

```ts
function config(
  /**
   * optional configuration options.
   * see types above at dotconfig.
   */
  options?: DotenvConfigOptions
): ConfigResult

type DotenvConfigOptions = {
  /**
   * The path to the dotenv file. Default is '.env' in the current working directory. May be set via DOTENV_CONFIG_PATH env var.
   */
  path?: string | URL | undefined
  /**
   * The encoding of the dotenv file. May be set via DOTENV_CONFIG_ENCODING env var.
   */
  encoding?: BufferEncoding | undefined
  /**
   * Whether to override existing process environment variables. Default is false. May be set by DOTENV_CONFIG_OVERRIDE env var.
   */
  override?: boolean | undefined
  /**
   * The process environment object to update. Default is `process.env`.
   */
  processEnv?: NodeJS.ProcessEnv | object
}

export type ConfigResult = {
  /** parsed .env file */
  parsed: Record<string, string | number | boolean> | {}
}
```

</details>

## getConfig

Applies the lower camel-cased `process.env` variables onto the default
configuration.

_Usage_

```js
import { getConfig } from '@commenthol/dotconfig'

process.env.HTTP_PORT = '8080'
process.env.HTTPS_PORT = '8443'

const config = getConfig({
  http: { port: 80 },
  https: { port: 443 }
})
//> config = {
//>  http: { port: 8080 },
//>  https: { port: 8443 }
//> }
```

# License

MIT licensed

[npm-badge]: https://badgen.net/npm/v/@commenthol/dotconfig
[npm]: https://www.npmjs.com/package/@commenthol/dotconfig
[npm-dm]: https://badgen.net/npm/dm/@commenthol/dotconfig
[types-badge]: https://badgen.net/npm/types/@commenthol/dotconfig
[dotenvx]: https://github.com/dotenvx/dotenvx

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