Readme.md

env2 - environment variable loader

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?

Need help getting started?

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 .gitignoreto 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: #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: #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)".

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: dshaw/env#6 and he said he would accept it ... But after investing the time and submitting the pull request: dshaw/env#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"