Awesome
dotenv-extended
I've been a big fan of the dotenv for a quite some time (in fact, this library uses dotenv under the hood for the .env
file parsing). However, while working on some bigger projects, we realized that the managing of the .env
files became a bit of a chore. As the files changed in the development environments, it became a tedious manual process to compare and figure out what needed to be added or removed in the other environments.
This library solves some of these issues by introducing the concept of 3 files which are used together to provide environment-specific variables, default values and a validation schema:
.env
The environment specific file (not committed to source control). This file will have sensitive information such as usernames, passwords, api keys, etc. These would be specific to each environment and should not be committed to source control. The format is a series of key-value pairs. Any line starting with #
or ;
are commented out and ignored.
# .env file
MONGO_HOST=localhost
MONGO_DATABASE=TestDB
MONGO_USER=dbusername
MONGO_PASS=dbpassword!
###.env.defaults
Common configuration defaults across all environments (commited to source control). This contains overall app configuration values that would be common across environments. The .env.defaults
file is loaded first and then the .env
file is loaded and will overwrite any values from the .env.defaults
file. Format is identical to the .env
file.
.env.schema
Defines a schema of what variables should be defined in the combination of .env
and .env.defaults
. Optionally, you can have the library throw an error if all values are not configured or if there are extra values that shouldn't be there.
The .env.schema
file should only have the name of the variable and the =
without any value:
MONGO_HOST=
MONGO_DATABASE=
MONGO_USER=
MONGO_PASS=
I have tried to stay as compatible as possible with the dotenv library but there are some differences.
Installation
npm i --save dotenv-extended
Usage
As early as possible in your main script:
require('dotenv-extended').load();
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:
MONGO_HOST=localhost
MONGO_DATABASE=TestDB
MONGO_USER=dbusername
MONGO_PASS=dbpassword!
process.env
now has the keys and values you defined in your .env
file.
mongoose.connect('mongodb://' + process.env.MONGO_HOST + '/' + process.env.MONGO_DATABASE, {
user: process.env.MONGO_USER,
pass: process.env.MONGO_PASS
});
Load Configs from command line
You may also load the .env
files from the command line. Add in the require dotenv-extended/config
along with any of the options that the load
method takes prefixed with dotenv_config_
. e.g.:
node -r dotenv-extended/config your_script.js
Or to specify load options:
node -r dotenv-extended/config your_script.js dotenv_config_path=./env/.env dotenv_config_defaults=./env/.env.defaults
Load Environment Variables and pass to non-NodeJS script
New in 2.0.0, is a feature inspired by cross-env to allow you to load environment variables from your .env
files and then pass them into a non-NodeJS script such as a shell script. This can simplify the process of maintaining variables used in both your Node app and other scripts. To use this command line executable, you will either need to install globally with the -g
flag, or install dotenv-extended
in your project and reference it from your npm scripts.
Install Globally:
npm install -g dotenv-extended
Now call your shell scripts through dotenv-extended
(this uses the defaults):
dotenv-extended myshellscript.sh --whatever-flags-my-script-takes
Configure dotenv-extended
by passing any of the dotenv-extended options before your command. Preceed each option with two dashes --
:
dotenv-extended --path=/path/to/.env --defaults=/path/to/.env.defaults --errorOnMissing=true myshellscript.sh --whatever-flags-my-script-takes
The following are the flags you can pass to the dotenv-extended
cli with their default values. these options detailed later in this document:
--encoding=utf8
--silent=true
--path=.env
--defaults=.env.defaults
--schema=.env.schema
--errorOnMissing=false # or --error-on-missing=false
--errorOnExtra=false # or --error-on-extra=false
--assignToProcessEnv=true # or --assign-to-process-env=true
--overrideProcessEnv=false # or --override-process-env=true
Options
Defaults are shown below:
require('dotenv-extended').load({
encoding: 'utf8',
silent: true,
path: '.env',
defaults: '.env.defaults',
schema: '.env.schema',
errorOnMissing: false,
errorOnExtra: false,
assignToProcessEnv: true,
overrideProcessEnv: false
});
The function always returns an object containing the variables loaded from the .env
and .env.defaults
files. The returned object does not contain the properties held in process.env
but rather only the ones that are loaded from the .env
and .env.defaults
files.
var myConfig = require('dotenv-extended').load();
encoding (default: utf8)
Sets the encoding of the .env
files
silent (default: true)
Sets whether a log message is shown when missing the .env
or .env.defaults
files.
path (default: .env)
The main .env
file that contains your variables.
defaults (default: .env.defaults)
The file that default values are loaded from.
schema (default: .env.schema)
The file that contains the schema of what values should be available from combining .env
and .env.defaults
errorOnMissing (default: false)
Causes the library to throw a MISSING CONFIG VALUES
error listing all of the variables missing the combined .env
and .env.defaults
files.
errorOnExtra (default: false)
Causes the library to throw a EXTRA CONFIG VALUES
error listing all of the extra variables from the combined .env
and .env.defaults
files.
assignToProcessEnv (default: true)
Sets whether the loaded values are assigned to the process.env
object. If this is set, you must capture the return value of the call to .load()
or you will not be able to use your variables.
overrideProcessEnv (default: false)
By defaut, dotenv-entended
will not overwrite any varibles that are already set in the process.env
object. If you would like to enable overwriting any already existing values, set this value to true
.
Examples
Consider the following three files:
# .env file
DB_HOST=localhost
DB_USER=databaseuser-local
DB_PASS=databasepw!
SHARE_URL=http://www.example.com
# .env.defaults
DB_USER=databaseuser
DB_DATABASE=MyAppDB
# .env.schema
DB_HOST=
DB_USER=
DB_PASS=
DB_DATABASE=
API_KEY=
Load files with default options
var myConfig = require('dotenv-extended').load();
myConfig.DB_HOST === process.env.DB_HOST === "localhost"
myConfig.DB_USER === process.env.DB_USER === "databaseuser-local"
myConfig.DB_PASS === process.env.DB_PASS === "localhost"
myConfig.DB_DATABASE === process.env.DB_DATABASE === "MyAppDB"
myConfig.SHARE_URL === process.env.SHARE_URL === "http://www.example.com"
Load files with errorOnMissing
var myConfig = require('dotenv-extended').load({
errorOnMissing: true
});
Throws ERROR `MISSING CONFIG VALUES: API_KEY`
Load files with errorOnExtra
var myConfig = require('dotenv-extended').load({
errorOnExtra: true
});
Throws ERROR `EXTRA CONFIG VALUES: SHARE_URL`
Contributing
See CONTRIBUTING.md
Change Log
See CHANGELOG.md
License
See LICENSE