# config-dug

> Config loader with support for AWS Secrets Manager

Latest version **1.10.1** (published 2026-07-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install config-dug
pnpm add config-dug
yarn add config-dug
bun add config-dug
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.10.1 |
| Published | 2026-07-15 |
| First published | 2019-04-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=20.0.0 |
| Dependencies | 3 |
| Unpacked size | 19.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Neo Financial Engineering |
| Maintainers | lucachamecki, kyle-elyk-neo, darrenpicard25, lucasparreira, neogibson, beraki, vrochamaaia, neobot1, kennethcolina, neo-lior-ben-shahar, antonio.canabrava, neo.eduardoyuidy, dennisbarthel, neo-engineering-b, iansu |
| Keywords | config, configuration, typescript, javascript, node |

## Links

- npm: https://www.npmjs.com/package/config-dug
- Repository: https://github.com/neofinancial/config-dug
- Issues: https://github.com/neofinancial/config-dug/issues
- npm.io page: https://npm.io/package/config-dug

## Dependencies (3)

- [debug](https://npm.io/package/debug.md) ^4.3.6
- [@aws-sdk/node-http-handler](https://npm.io/package/@aws-sdk/node-http-handler.md) ^3.374.0
- [@aws-sdk/client-secrets-manager](https://npm.io/package/@aws-sdk/client-secrets-manager.md) ^3.1086.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

- 1.10.1 (latest) — 2026-07-15
- 2.0.0-alpha.3 (alpha) — 2025-03-11
- 2.0.0 (rc) — 2025-02-12
- 1.9.0-next.0 (next) — 2024-09-16
- 1.10.0 — 2025-10-02
- 1.9.1-RC.1 — 2025-09-08
- 2.0.0-alpha.4 — 2025-03-11
- 2.0.0-alpha.2 — 2025-03-06
- 2.0.0-alpha.1 — 2025-01-03
- 1.9.0 — 2024-09-16
- 1.8.0 — 2024-09-05
- 1.8.0-next.2 — 2024-08-27
- 1.8.0-next.1 — 2024-08-23
- 1.8.0-next.0 — 2024-08-23
- 2.0.0-alpha.0 — 2023-12-29
- … 15 more at https://npm.io/package/config-dug/versions

## README

# Config Dug

[![Build status](https://github.com/neofinancial/config-dug/workflows/CI/badge.svg)](https://github.com/neofinancial/config-dug/actions)
[![coverage](https://coverage.neotools.ca/api/badge/master/4C8hhW7NzS4PKdA9C3NqNM)](https://coverage.neotools.ca/coverage/neofinancial/config-dug)
[![codecov](https://codecov.io/gh/neofinancial/config-dug/branch/master/graph/badge.svg)](https://codecov.io/gh/neofinancial/config-dug)
![TypeScript 3.7.2](https://img.shields.io/badge/TypeScript-3.7.2-brightgreen.svg)

![Config Dug](https://github.com/neofinancial/config-dug/blob/master/config-dug.png)

Config loader with support for AWS Secrets Manager.

## Usage

### Installation

| yarn                  | npm                      |
| --------------------- | ------------------------ |
| `yarn add config-dug` | `npm install config-dug` |

### Create your config files

`config-dug` looks in several places for your config, including config files in your project, environment variables and [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/). `config-dug` allows you to write your config files in either TypeScript or JavaScript. You are expected to export a default object from your config file:

```ts
// config.default.ts
export default {
  API_ENDPOINT: 'https://api.example.com/',
};
```

```js
// config.default.js
module.exports = {
  API_ENDPOINT: 'https://api.example.com/',
};
```

Environment specific config files are loaded based on the value of the `APP_ENV` or `NODE_ENV` environment variables. If `APP_ENV` is present it will take precedence over `NODE_ENV`.

Settings from these different sources are merged together into a single config object in the following order:

1. `config.default.{ts|js}`
1. `config.${APP_ENV|NODE_ENV}.{ts|js}`
1. `config.${APP_ENV|NODE_ENV}.local.{ts|js}`
1. `config.local.{ts|js}`
1. AWS Secrets Manager
1. Environment variables

By default your config files need to be placed in the root directory of your project. If you want to keep config files in a different directory see [Customizing Config Loading](#customizing-config-loading).

### Import config

Import `config-dug` anywhere in your code where you want to access your config. All of your settings are available on the imported object:

```ts
// app.ts
import config from 'config-dug';

console.log(config.API_ENDPOINT);
```

```js
// app.js
const config = require('config-dug').default;

console.log(config.API_ENDPOINT);
// https://api.example.com/
```

> :warning: You must use `require('config-dug').default` in JavaScript files. If you exclude `.default` Config Dug will not work.

### Environment Variables

`config-dug` will add all your environment variables to the `config` object. This can have unintended consequences if one of your config keys has the same name as an existing, unrelated environment variable.

> :warning: `config-dug` is only intended to be used on the server. Your server already has access to your full environment in `process.env`. If you use `config-dug` in server rendered client applications you risk exposing your server's environment to the client.

### Using AWS Secrets Manager

In order to use AWS Secrets Manager you have to add a `AWS_SECRETS_MANAGER_NAME` or `awsSecretsManagerName` setting to your config that specifies the names of the secrets to look up:

```ts
// config.default.ts
export default {
  AWS_SECRETS_MANAGER_NAME: 'production/myapp/config',
  API_ENDPOINT: 'https://api.example.com/',
};
```

If you need to read from multiple secret buckets, `AWS_SECRETS_MANAGER_NAMES` takes a comma separated list to allow connection to multiple secrets in AWS Secrets Manager. Each secret from the list is evaluated in order mean that if a specific key appears in two secrets the value will be overwritten by the last secret in the list.

```ts
// config.default.ts
export default {
  AWS_SECRETS_MANAGER_NAMES: 'production/myapp/config,production/myapp/another-config',
  API_ENDPOINT: 'https://api.example.com/',
};
```

In addition to specifying the secret name you can also provide a region using the `AWS_SECRETS_MANAGER_REGION` or `awsSecretsManagerRegion` setting. The connection timeout in milliseconds can also be specified using the `AWS_SECRETS_MANAGER_TIMEOUT` or `awsSecretsManagerTimeout` setting:

```ts

// config.default.ts
export default {
  AWS_SECRETS_MANAGER_NAME: 'production/myapp/config',
  AWS_SECRETS_MANAGER_REGION: 'us-west-2',
  AWS_SECRETS_MANAGER_TIMEOUT: 2000
  API_ENDPOINT: 'https://api.example.com'
};
```

The default region is `us-east-1` and the default connection timeout is `5000`ms.

Config Dug will warn if it detects invalid config values. Invalid values include:

- undefined
- null
- the string 'undefined'
- an empty string

This package uses the [aws-sdk](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/) internally. Refer to their documentation for information about [authentication](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html), configuring a default [region](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html) and configuring [access control for AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html).

## Advanced

### Customizing Config Loading

If you want to load config files from a directory other than the project root you can import the `loadConfig` function and use it directly.

```ts
import { loadConfig } from 'config-dug';

loadConfig('config');
```

This will import your config files from the `config` directory. The path you specify must be relative to your project root.

### Debugging

`config-dug` uses the [debug](https://github.com/visionmedia/debug) library. To print debug messages for `config-dug` set `DEBUG=config-dug`.

## Contributing

### Running Tests

1. Fork this repo
1. Clone the forked repo
1. Install dependencies: `npm install` OR `npm i`
1. Run tests: `npm run test`

## Publishing

1. Update the version in `package.json`
1. Add a `CHANGELOG` entry
1. Commit your changes
1. Run `npm pack` to see what will be published then delete the `.tgz` file that was created
1. Run `npm publish`
1. Create a release on GitHub. Use the version as the tag and release name. For example for version `1.0.0` the tag and release name would be `v1.0.0`.

## Credits

This project was inspired by [config3](https://github.com/focusaurus/config3) and [config4](https://github.com/autolotto/config4).

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