renvy - a sensible and controllable env file loader

A bit like foreman, uses dotenv and comes from the create-react-app environment loader code.

Installation

npm install --save renvy

Typical usage

Important: renvy will default to NODE_ENV=development if there is no value on NODE_ENV.

// populates process.env
require('renvy'); // do this as early as possible in the code

// Also populate and return
const { raw, stringified } = require('renvy');

Runtime reloading (prioritiseFiles)

A new exported function prioritiseFilesReloads the environment by re-reading the dotenv files in the same priority order as startup, while preserving the original startup environment.

• The function is prioritiseFiles (note the British spelling) and is exported from index.js as module.exports.prioritiseFiles.
• It captures the original environment, then loads the dotenv files in the same sequence used at startup:
  • .env.<NODE_ENV>.local
  • .env.<NODE_ENV>
  • .env.local (only if NODE_ENV is not 'test')
  • .env
• Values loaded from these files are merged with later files overriding earlier ones. The result overwrites process.env, but the original environment captured at startup is preserved in the return value.

Usage example:

const { prioritiseFiles } = require('./index.js');

// Reload process.env according to the configured priority.
prioritiseFiles();

Notes:

• This mirrors the startup behaviour, but prioritises the local .env files over the existing environment.

Env file loading priority

Files on the left have more priority than files on the right:

• renvy: .env.development.local, .env.development, .env.local, .env
• NODE_ENV=production renvy: .env.production.local, .env.production, .env.local, .env
• npm test: .env.test.local, .env.test, .env (note .env.local is missing)

What `.env` files can be used?

• .env: Default.
• .env.local: Local overrides. This file is loaded for all environments except test.
• .env.development, .env.test, .env.production: Environment-specific settings.
• .env.development.local, .env.test.local, .env.production.local: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right:

• npm start: .env.development.local, .env.development, .env.local, .env
• npm run build: .env.production.local, .env.production, .env.local, .env
• npm test: .env.test.local, .env.test, .env (note .env.local is missing)

These variables will act as the defaults if the machine does not explicitly set them.

Please refer to the dotenv documentation for more details.

Note: If you are defining environment variables for development, your CI and/or hosting platform will most likely need these defined as well. Consult their documentation how to do this. For example, see the documentation for Travis CI or Heroku.

Features

• Expands $VAR by default (via dotenv-expand). Important escaped \$ does not work, and is expanded to undefined. To disable env expansion, set environment value NO_EXPAND=true.
• Supports .env.example if the file is found in the current working directory (very similar to dotenv-safe - but merges environment values first, then checks)

CLI usage

Beyond using the package as a dependency, a CLI utility is provided for testing environment values and also injecting the environment variables into a command.

Assuming the package was installed locally to your project, and using npx to run a .bin command:

$ NODE_ENV=test npx renvy
> # prints entire environment loaded

$ NODE_ENV=test npx renvy NODE_ENV
> test

$ NODE_ENV=test npx renvy -- node -e "console.log(process.env.NODE_ENV)"
> test

-- Double dash to signify the end of the options

When passing -- to renvy everything afterwards will be executed with the modified environment (a bit like the foreman command line too).

Naming

renvy is weird, but it comes from it previously being called @remy/envy and since the envy namespace was gone and people feel weird about installed scoped dependencies when they belong to individuals, I slapped my first initial on the name, thus: renvy.