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.kanye.rest/',
};
// config.default.js
module.exports = {
API_ENDPOINT: 'https://api.kanye.rest/',
};
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:
config.default.{ts|js}
config.${APP_ENV|NODE_ENV}.{ts|js}
config.${APP_ENV|NODE_ENV}.local.{ts|js}
config.local.{ts|js}
- AWS Secrets Manager
- 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.kanye.rest/
⚠️ You must userequire('config-dug').default
in JavaScript files. If you exclude.default
Config Dug will not work.
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.kanye.rest/',
};
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.kanye.rest/',
};
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.somecompany.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 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
- Fork this repo
- Clone the forked repo
- Install dependencies:
npm install
ORnpm i
- Run tests:
npm run test
Publishing
- Update the version in
package.json
- Add a
CHANGELOG
entry - Commit your changes
- Run
npm pack
to see what will be published then delete the.tgz
file that was created - Run
npm publish
- 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 bev1.0.0
.