config-dug
v1.6.0Config 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:
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.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 inprocess.env
. If you useconfig-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 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
.
Credits
Metadata
- MIT
- >=8.0.0
- Neo Financial Engineering
- released 10/26/2020