Config Dug

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. 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:

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

// 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}
2. config.${APP_ENV|NODE_ENV}.{ts|js}
3. config.${APP_ENV|NODE_ENV}.local.{ts|js}
4. config.local.{ts|js}
5. AWS Secrets Manager
6. 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.

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:

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

console.log(config.API_ENDPOINT);

// 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:

// 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.

// 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:

// 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 5000ms.

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 internally. Refer to their documentation for information about authentication, configuring a default region and configuring access control for AWS Secrets Manager.

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.

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 library. To print debug messages for config-dug set DEBUG=config-dug.

Contributing

Running Tests

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

Publishing

1. Update the version in package.json
2. Add a CHANGELOG entry
3. Commit your changes
4. Run npm pack to see what will be published then delete the .tgz file that was created
5. Run npm publish
6. 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 and config4.