    eslint dependency version !npm bundle size !npm downloads !NPM License
This script pulls vars from multiple sources, merges them, and outputs the result.
It can read from AWS Secrets Manager and local .env files.
The output can be written to a .env file (compile command) or displayed as JSON in the console (show-json command).
Create a JSON configuration file at {project root}/.envelop.config.json. You may specify a different filename using the --config flag.
Create a package script to run yarn envelup compile --config {your config file} ... during your local dev spin up and remote deployment pipelines.
Examples below assume a short project name of abc.
Please see the examples/ directory for complete examples.
The configuration file should contain an environments entry which is an object of environments each containing an array of input sources.
``
{
"environments": {
"local": [
"aws:us-west-2:abc/low-security:index.local",
"file:./.envs/.env.default",
"file:./.envs/.env.local"
],
"dev": [
"aws:us-west-2:abc/project-server:index.dev",
"file:./.envs/.env.default",
"file:./.envs/.env.dev"
],
"production": [
"aws:us-west-2:abc/production:index.production",
"file:./.envs/.env.default",
"file:./.envs/.env.production"
]
}
}
Input sources may be AWS Secrets, local files, or individual values:
* AWS Secret: aws:{region}:{secretName}?(:{dot.notation.path})
* Local file:
* Individual value:
Values in subsequent input sources will overwrite values in previous input sources.
To use vars stored in AWS Secrets Manager, you must install the aws cli and authenticate with it.
To authenticate on local environments, add the following values to .envs/.env.local:
`
ENVELUP_AWS_ACCESS_KEY_ID=*
ENVELUP_AWS_SECRET_ACCESS_KEY=*
Alternatively, you may define named profiles using the AWS CLI and/or ~/.aws/config and ~/.aws/credentials files as described in AWS documentation, and then add the following to .envs/.env.local:
`
ENVELUP_AWS_PROFILE=your_aws_profile_name
Variables starting with ENVELUP_ will be stripped out, and will not be available to your application at runtime.
Store values in a combination of version-controlled .env files and non-version-controlled AWS Secrets.
Non-sensitive information, such as URLs and app config values, belongs in .env files that are committed to the repository.
Place these .env.* files in a subdirectory named .envs off of the project root.
Create a .env.default file for default values that are shared across environments.
Create an environment-specific file for each environment, named .env.dev, env.production, etc. Place values in these files as needed to override the values in .env.default.
Local developers will need to have their own .env.local file, and it must be gitignored. All other .env.* files should be committed to the repository.
#### Structure of values in .env files
Store values in .env.* files using standard .env syntax, for example:
`
APP_NAME=abc.com
APP_TIMEZONE=America/Los_Angeles
Sensitive information, such as API keys and passwords, belongs in AWS Secrets Manager.
Secrets should be stored in AWS with a prefix of {short project name}/.
Information should be stored in multiple Secrets based on security level, so that individuals can be granted access to only what they need.
Create the following Secrets in AWS:
* {short project name}/low-security - all developers will be given access to this secret. It should contain all sensitive information that a developer needs to run the app locally, as well as default information that is used on both local and remote testing environments.{short project name}/project-server
* - developers should not need access to this secret in order to run the app locally. It should contain all sensitive information that remote testing environments running on the project server need in order to run.{short project name}/production
* - developers should not need access to this secret in order to run the app locally, and should only be given access if they are trusted with the production environment. It should contain all sensitive information that the production environments need in order to run.
#### Structure of secrets in AWS Secrets Manager
Secrets in AWS are full-fledged JSON objects.
Env var key-value-pairs are stored in JSON objects, for example:
`
{
"DATABASE_URL": "mysql://...",
"DATABASE_PASSWORD": "*",
}
Dot notation can be used to reference sub-objects in an AWS secret. For example, backend.production will return { APP_URL: "https://my-project.com" } for this example:
`
{
"backend": {
"production": {
"APP_URL": "https://my-project.com"
}
}
}
Indexes allow variables to be reused across multiple environments.
Define variables for all environments under a "default" object, and then override them as needed on a per-environment basis by defining "local", "dev", "production", etc objects.
Then use your index to define the order in which the variables should be brought in. Indexes must be JSON arrays.
`
{
"index": {
"local": ...,
"dev": ...,
"production": {
"backend": [
"us-west-2:my-project:default",
"us-west-2:my-project:production"
]
}
},
"default": {
...secrets...
},
"production": {
...secrets...
}
}
You can reference env variables within other env variables.
BAR will evaluate to "foo-bar":
`
FOO=foo
BAR="${FOO}-bar"
A variable does not need to come before another variable in order to be used in a replacement. This is true even if the variables are in different input sources. Interpolation takes place after all variables have been loaded into memory.
This works: BAR will evaluate to "foo-bar":
`
BAR="${FOO}-bar"
FOO=foo
Be aware that deep interpolation is only supported if the referenced value has already been interpolated, which is governed by the order of the variables.
BAZ will resolve to "foo-bar-baz":
`
FOO=foo
BAR="${FOO}-bar"
BAZ="${BAR}-baz"
BAZ will resolve to "${FOO}-bar-baz":
`
BAZ="${BAR}-baz"
FOO=foo
BAR="${FOO}-bar"
The show-json command is useful for converting existing .env files to JSON to be stored in AWS. Use it to compile you existing .env file(s), and copy the results into AWS Secrets Manager.
1. Run yarn
Run yarn envelup --help` for usage.