patsissons / dotenv-multi

dotenv for multiple files based on NODE_ENV

dotenv-multi

dotenv-multi is an extension to dotenv that loads environment variables from multiple .env* files based on NODE_ENV into process.env.

Install

# with npm
npm install --dev dotenv-multi

# or with Yarn
yarn add -D dotenv-multi

Usage

As early as possible in your application, require and configure dotenv-multi.

require('dotenv-multi').config();

import {config} from 'dotenv-multi';

confg();

Create a .env file in the root directory of your project. Add environment-specific variables on new lines in the form of NAME=VALUE. For example:

DB_HOST=localhost
DB_USER=root
DB_PASS=s1mpl3

That's it.

process.env now has the keys and values you defined in your .env file.

const db = require('db');
db.connect({
  host: process.env.DB_HOST,
  username: process.env.DB_USER,
  password: process.env.DB_PASS,
});

What other .env* files can I use?

dotenv-multi will override in the following order (highest defined variable overrides lower):

Hierarchy Priority	Filename	Environment	Should I .gitignoreit?	Notes
1st (highest)	.env.development.local	Development	Yes!	Local overrides of environment-specific settings.
1st	.env.test.local	Test	Yes!	Local overrides of environment-specific settings.
1st	.env.production.local	Production	Yes!	Local overrides of environment-specific settings.
2nd	.env.local	Wherever the file is	Definitely.	Local overrides. This file is loaded for all environments except test.
3rd	.env.development	Development	No.	Shared environment-specific settings
3rd	.env.test	Test	No.	Shared environment-specific settings
3rd	.env.production	Production	No.	Shared environment-specific settings
Last	.env	All Environments	Depends (See below)	The Original®

Preload

You can use the --require (-r) command line option to preload dotenv. By doing this, you do not need to require and load dotenv-multi in your application code. This is the preferred approach when using import instead of require.

$ node -r dotenv-multi/config your_script.js

Config

Alias: load

config will read your .env* files, parse the contents, assign it to process.env, and return an Object with a parsed key containing the loaded content or an error key if it failed.

const result = dotenv.config();

if (result.error) {
  throw result.error;
}

console.log(result.parsed);

You can additionally, pass options to config.

Options

basePath

Default: path.resolve(process.cwd(), '.env')

You may specify a custom base path if your file containing environment variables is located elsewhere.

require('dotenv').config({basePath: '/full/custom/path/to/your/env/vars/.env'});

encoding

Default: utf8

You may specify the encoding of your file containing environment variables.

require('dotenv').config({encoding: 'latin1'});

debug

Default: false

You may turn on logging to help debug why certain keys or values are not being set as you expect.

require('dotenv').config({debug: process.env.DEBUG});

Parse

The engine which parses the contents of your file containing environment variables is available to use. It accepts a String or Buffer and will return an Object with the parsed keys and values.

const dotenv = require('dotenv-multi');
const buf = Buffer.from('BASIC=basic');
const config = dotenv.parse(buf); // will return an object
console.log(typeof config, config); // object { BASIC : 'basic' }

Options

debug

Default: false

You may turn on logging to help debug why certain keys or values are not being set as you expect.

const dotenv = require('dotenv-multi');
const buf = Buffer.from('hello world');
const opt = {debug: true};
const config = dotenv.parse(buf, opt);
// expect a debug message because the buffer is not in KEY=VAL form

Rules

The parsing engine currently supports the following rules:

• BASIC=basic becomes {BASIC: 'basic'}
• empty lines are skipped
• lines beginning with # are treated as comments
• empty values become empty strings (EMPTY= becomes {EMPTY: ''})
• single and double quoted values are escaped (SINGLE_QUOTE='quoted' becomes {SINGLE_QUOTE: "quoted"})
• new lines are expanded if in double quotes (MULTILINE="new\nline" becomes

{MULTILINE: 'new
line'}

• inner quotes are maintained (think JSON) (JSON={"foo": "bar"} becomes {JSON:"{\"foo\": \"bar\"}")
• whitespace is removed from both ends of the value (see more on trim) (FOO=" some value " becomes {FOO: 'some value'})

FAQ

What happens to environment variables that were already set?

We will never modify any environment variables that have already been set. In particular, if there is a variable in your .env file which collides with one that already exists in your environment, then that variable will be skipped. This behavior allows you to override all .env configurations with a machine-specific environment, although it is not recommended.

If you want to override process.env you can do something like this:

const fs = require('fs');
const dotenv = require('dotenv-multi');
const envConfig = dotenv.parse(fs.readFileSync('.env.override'));
for (let k in envConfig) {
  process.env[k] = envConfig[k];
}

What about variable expansion?

Try dotenv-expand

Contributing Guide

See CONTRIBUTING.md

Change Log

See CHANGELOG.md

License

See LICENSE