dotenv-tools
Dotenv-tools is a zero-dependency plugin for dotenv, adding some small, commonly needed tools. There are other dotenv plugins which achieve some of the tasks here, but I felt there was too much going on to achieve a very simple goal; load the environment variables they way I'd expect them to load.
Node's process.env
can only store strings, so if using the castVars()
function, store the result to a local and/or global variable, and reference it instead of process.env
directly. In the example below, I use GLOBAL.env
and env
for full coverage.
Features include:
- Specify a file other than
.env
to load using an environment variable or command line argument. - Change the default
.env
file that dotenv loads. - Run projects outside of the project path, and still have dotenv pick up the
.env
file local to the project source. - Returns an object with the newly casted environment variables for you to write to local or global variable.
- Read the values of the
.env
file, and automatically cast them as boolean, numeric, or objects. - Option to disable casting of specific primitive types.
- Option to skip casting by ending string with a special character. By default,
*
. - Only use the tools you want.
Examples of running from command line using alternate dotenv file:
# Single execution defining dotenv file via command line argument node myapp.js --config=.env_alternate # Single execution defining dotenv file via environment variable: DOTENV_CONFIG=.env_alternate node myapp.js # Define dotenv file once via environment variable, and have it persist for the duration of your session: export DOTENV_CONFIG=.env_alternatenode myapp.js
Example .env with castable variables:
WILL_BE_NUMERIC_A=123WILL_BE_NUMERIC_B=123.456WILL_BE_STRING_A=abcWILL_BE_STRING_B='def'WILL_BE_STRING_C="ghi"WILL_BE_STRING_D=true*WILL_BE_STRING_E=1234*WILL_BE_STRING_F=["a","b","c"]*WILL_BE_STRING_G={"j": 1, "k": 2, "l": 3}*WILL_BE_STRING_H='{"debug":"on","window":{"title":"Sample Widget","name":"main_window","dimentions":[500,500]}}*'WILL_BE_BOOLEAN_A=trueWILL_BE_BOOLEAN_B=falseWILL_BE_BOOLEAN_C='true'WILL_BE_BOOLEAN_D='false'WILL_BE_OBJECT_A=[5,6,7]WILL_BE_OBJECT_B=["a","b","c"]WILL_BE_OBJECT_C='["d","e","f"]'WILL_BE_OBJECT_D='[ "g" , "h" , "i" ]'WILL_BE_OBJECT_E={"j": 1, "k": 2, "l": 3}WILL_BE_OBJECT_F={"debug":"on","window":{"title":"Sample Widget","name":"main_window","dimentions":[500,500]}}WILL_BE_OBJECT_G='{"debug":"on","window":{"title":"Sample Widget","name":"main_window","dimentions":[500,500]}}'
Example usage, using default setup:
// Require dotenv-toolsvar dotEnvTools = ; // Create dotenv config object using default dotenv-tools settingsvar dotenvCfg = dotEnvTools; // Start dotenv with created config object; // Cast process.env variables to likely natives, and save result as both local var env and global.envvar env = GLOBALenv = dotEnvTools;
Example usage, using custom setup:
// Require dotenv-toolsvar dotEnvTools = ; // Configure dotenv-toolsdotEnvTools; // Create dotenv config object passing in addional config for returning dotenv objectvar dotenvCfg = dotEnvTools; // Start dotenv with created config object; // Cast process.env variables to likely natives, and save result as both local var env and global.envvar env = GLOBALenv = dotEnvTools;
Config options, and their defaults:
// Debug castingdebugCasting: false // Default file nameenvFileName: '.env' // Environment variable to look for to override default file nameconfigKeyEnv: 'DOTENV_CONFIG' // Command line argument to look for to override default file nameconfigKeyArg: 'config' // Character to look for, signaling to skip cast attemptpassthroughChar: '*' // Exit if the .env file is not foundrequireFile: true // Try casting strings to numberscastNumbers: true // Try casting strings to booleanscastBooleans: true // Try casting JSON strings to objects. Failure to cast, value remains stingcastJson: true