README

`envars` — environment variables loader

Envars is a Node.js module based on dotenv that loads and decrypts environment variables from .{envName}.env files into process.env.

It allows to store application secrets in .env.* files encrypted making these files safe to be committed into a source control repository.

How to Install

# with NPM
$ npm install envars --save-dev

# with Yarn
$ yarn add envars --dev

Getting Started

Suppose you have local (local development), test (test/QA), and prod (production) application environments. For each of these environments you would create a separate .{envName}.env file in your project. For example:

# .local.env
APP_ORIGIN=http://localhost:8080
PGHOST=127.0.0.1
PGDATABASE=example_local
PGUSER=postgres
PGPASSWORD=

# .test.env
APP_ORIGIN=http://test.example.com
PGHOST=34.72.79.184
PGDATABASE=example_test
PGUSER=postgres
PGPASSWORD=enc::mxJIZ9/1uV/NDgwT:Seheo3XvJlbllbLg:M5kwPZ3XYK14rbUctbxN/3z18Q==

# .prod.env
APP_ORIGIN=http://example.com
PGHOST=34.72.79.1
PGDATABASE=example
PGUSER=postgres
PGPASSWORD=enc::oiF6UkepsP2l41Mt:Et1jQuh7Vw3X4UpA:Qv3Lhr45ZPA0jga5QKeg917UDg==

# .gitignore
*.override.env

While the .local.env file, that is used during local development, will contain all the configuration settings in plain text, the other two may have some secret values such as live database password, JWT secret, etc. Since these values will be encrypted, it would be totally OK to commit these files into the source control repository without compromising security.

You can update and read secrets by using the envars CLI:

# Encrypt and save `PGPASSWORD` variable into the `.prod.env` file
$ yarn envars set PGPASSWORD "S^6wh:rruq!MS(Xd" --env=prod --secret

# Read and decrypt `PGPASSWORD` variable from the `.prod.env` file
$ yarn envars get PGPASSWORD --env=prod

Get more information by running yarn envars --help.

From there on, loading and passing the environment variables into your app would be as simple as requiring envars/config module at run-time.

# Load environment variables when launching a Node.js app
$ node -r envars/config ./server.js

# Load environment variables when launching a Node.js app via Nodemon
$ nodemon -r envars/config ./server.js

# Load environment variables for "prod" environment instead of "local" (default)
$ APP_ENV=prod nodemon -r envars/config ./server.js

Alternatively, you can load environment variables programmatically:

import { config } from "envars";

config({ env: "prod" });

Q&A

❓ In which order the `.env` files are being loaded?

1) .{envName}.override.env
2) .{envName}.env
3) .common.override.env
4) .common.env
5) .env

Where {envName} is the name of the target environment (defaults to local).

❓ How to check which environment is being used at run-time

By reading the value of process.env.APP_ENV.

❓ Which files needs be included into the source control?

As long as you store secrets encrypted it is safe to commit all the .*.env files into the source control repository except for the .*.override.env files.

❓ What's the purpose of `.*.override.env` files?

Sometimes it's required for a developer being able to override some of the configuration settings without pushing these changes to the upstream repository. These files also used to store encryption/decryption master password.

❓ How to customize where it looks for `.*.env` files?

You can customize it by adding envars settings to package.json:

{
  "name": "app",
  "dependencies": {
    "envars": "x.x.x",
    ...
  },
  "envars": {
    "cwd": "./env",       // defaults to "." when omitted
    "default": "dev",     // defaults to "local" when omitted
    "encoding": "latin1", // defaults to "utf-8" when omitted
    "debug": true         // defaults to "false" when omitted
  }
}

Related Projects

React Starter Kit — front-end boilerplate (TypeScript, React, Material UI, Webpack 5)
GraphQL API and Relay Starter Kit — monorepo boilerplate (TypeScript, GraphQL.js, React, and Relay)
Node.js API Starter Kit — Node.js boilerplate (TypeScript, Knex, GraphQL, Cloud SQL, Cloud Functions)

How to Contribute

Please create a PR or send me a message on Discord.

License

^{Made with ♥ by Konstantin Tarkus (@koistya, blog)
and contributors.}

Usage no npm install needed!