Awesome
env2 - environment variable loader
<div align="center"> </div>Why?
Environment variables are the best way of storing sensitive data like API Keys, Login Credentials and Database Passwords.
If you are new to environment variables please checkout our introduction for complete beginners: https://github.com/dwyl/learn-environment-variables
We needed a simple/reliable way of managing environment variables; and being able to share a configuration file among the team (without committing it to GitHub!) env2 is our solution.
What?
env2 allows you to store your environment variables in an env.json
or a
.env
file which gets loaded when your app starts.
All the entries in the env
file are exported as environment variables
available as keys in the process.env
object.
Works fine with build systems like webpack and browserify.
If you want to use it on the frontend, you will need some sort of filesystem shim
How?
Create a .env
File
We use (and recommend) .env
files for environment configuration.
We call our file .env
for cross-project consistency and .env
is part of the official .gitignore
from GitHub for NodeJS.
(but you can call your file what ever you like e.g: .environment
)
A .env
file is a very explicit way of listing environment variables
without the extra syntax (potential human/input error) of a JSON file.
It also allows for easier copy-pasting into the terminal
(with an export
keyword prepended to each line).
The format of a .env
file is:
export DB_HOST=127.0.0.1
export DB_PORT=9200
export DB_USER=anon
export DB_PASS=password
Note the lack of spaces. You may leave blank lines and insert comments (starting with '#') to organise the file if you wish. Follow the instructions below for placing it in your
.gitignore
file.
Alternatively Create an env.json
Configuration File
If you prefer to use .json
instead of .env
create a env.json
file in your repo with the following format:
{
"DB_HOST": "127.0.0.1",
"DB_PORT": 9200,
"DB_USER": "anon",
"DB_PASS": "password"
}
Always .gitignore
your configuration file
Always create your .env
or env.json
file
in the root directory of your project and don't forget to add it to your .gitignore
to
avoid accidentally committing your keys/passwords to GitHub where bad people can (will) steal your secrets!
e.g:
echo '.env' >> .gitignore
or
echo 'env.json' >> .gitignore
Install from NPM
Next install env2
from npm and save it to your package.json
file:
npm install env2 --save
Use in your Code
Then in your script/module:
const env = require('env2')('./path-to-your/.env');
// your app goes here
console.log(process.env.DB_HOST); // "127.0.0.1"
now all the entries in your env.json
or .env
file are available as
keys/values of the process.env
Object which means you can use
process.env.API_KEY
or process.env.DB_PASSWORD
in your script.
(or what ever you have defined as entries in your env.json
)
Env is synchronous; it loads all your configuration variables into the
process.env
object before app/script execution.
Do you want to Define Priority for Variables?
Do you want the ability to specify the priority which
environment variables take precendence?
e.g: if you supply a command-line argument when running your script/app:
env=PROD API_KEY=token.dwyl.yolo node myapp.js
We have an open discussion on this: https://github.com/dwyl/env2/issues/1
At present, any environment variable defined in the environment where
your app is running (or via command-line arguments) will take
precendence over the same key in your env.json
file ... if you prefer
to have the option to specify the priority, please add a comment to the isssue:
https://github.com/dwyl/env2/issues/1
Huh?
The Twelve Factor App section 3 states:
"Store config in the environment"
"An app’s config is everything that is likely to vary between deploys (staging, production, developer environments, etc)".
<br />Name ?
Q: Why is it called "env2"?
A: as the digit in the name suggests, there was/is an "env" (version 1):
https://www.npmjs.com/package/env written by @dshaw
sadly, it was never finished and has not been updated in 4 years ...
We asked Dan if he would accept a Pull Request updating the package:
https://github.com/dshaw/env/issues/6 and he said he would accept it ...
But after investing the time and submitting the pull request:
https://github.com/dshaw/env/pull/8 which updated the package to the latest
version of Node/io.js and had tests with 100% coverage, the PR got ignored.
see: https://twitter.com/dshaw/status/628237150253772801
Not that we're "impatient" but we need to move on with our code/lives.
That's why we wrote env2.
We have since added better error handling and alternative file types, so env2 is can be considered the "New & Improved Version"