Environment-variable based config for node

npm install @mcrowe/gotenv@0.0.2



Environment-variable based config for node.


Gotenv offers a clean, robust, and secure way to configure your node applications. It is based on the following principles:

  • Configuration via environment variables is one honking good idea
  • Despite what the 12factor doctrine suggests, it is a good a idea to have separate configurations for dev/test environments in your code base
  • Required and optional environment variables for an application should be well documented in a conventional place.
  • Your app should abort and report if required environment variables are missing, rather than breaking in unpredictable ways.
  • Parsing and validating format of environment variables is the app developer's job


  • Parses a .env file for enviroment variables if present
  • If NODE_ENV=test then it looks for a .env.test file instead and defaults to .env if missing
  • Validates required enviroment variables, documented in your package.json (see below)

Why not "D"otenv

Dotenv is a great package, and I have borrowed much of its functionality here. I feel that it gets 3 things wrong, though:

  1. It does not allow you to specify a separate .env file for your test environment. While 12-factor-y, this is very inconvenient. Almost all apps need separate configuration for their dev/test environments, and this should live within the codebase for convenience. Other enviroments like production, staging, qa, etc. should be configured directly via environment variables specified by the enviroment they are running in.

  2. It doesn't allow you to overwrite global environment variables in your .env files. If you have, say, PORT=5000 in your .bashrc for some reason, then any value you set in your .env will be ignored. This bit me when I was setting AWS credentials for my projects.

  3. It doesn't validate required enviroment variables, which I believe should be done for all applications.


Install it:

npm install @mcrowe/gotenv --save

Add the following to your .gitignore:


Create a .env.example file with example environment variables (its OK to check this in to git).


Have each developer copy .env.example to .env and set their own custom enviroment variables. This file should not be commited to git.

Add an "env" section to your package.json, specifying your environment variables.

"env": {
  "required": {
    "SERVICE_URL": "URL for the super service",
    "CONCURRENCY": "Number of concurrent workers to run",
  "optional": {
    "LOG_LEVEL": "Log level [debug, info, error] (defaults to 'info')",

Import or require this module at the top of your program:

// ES6
import '@mcrowe/gotenv'

// ES5

Or, require it when invoking node:

node -r @mcrowe/gotenv src/index.js


Install npm modules:

npm install

Run tests:

npm test


Release a new version:


This will publish a new version to npm, as well as push a new tag up to github.