Skip to content
Lightweight, zero-dependency library for using .env files in Node applications
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
src
tests
.eslintrc.json
.gitignore Use Jest for testing Jan 5, 2020
.npmignore Use Jest for testing Jan 5, 2020
.npmrc Add .npmrc Sep 15, 2019
LICENSE Initial commit Jan 4, 2019
README.md Use consistent quote style Aug 20, 2019
index.js
package.json Use Jest for testing Jan 5, 2020

README.md

env-smart

Zero-dependency library for using .env files with types and defaults

env-smart is a lightweight, zero-dependency library for loading environmental variables from .env files. It is designed to solve two common issues with using .env configuration:

  • Variable types
  • Default values

In both sitautions, logic specific to the environmental variables (type casting, default checking) ends up seeping into the application logic. If any of these values are re-used in different parts of the app this can even lead to duplication.

Instead, env-smart enables defining default values and types for all environmental variables in their own configuration files. It supports .env files if one is defined, but defaults and type checking are applied to the process' env if not.

Install

$ npm install env-smart

Usage

require('env-smart').load();

// process.env is now populated with the contents of the .env file

console.log(process.env.PORT);

All configuration files are optional. If none are included, env-smart will use the process env. If a .env file is included, it will load that. Types and defaults are applied if declared.

Types are defined in the .env.types file:

PORT=number
VERBOSE=boolean

Default values are defined in the .env.defaults file:

PORT=80
VERBOSE=FALSE

Alternatively, you can declare both default values and types in the .env.defaults file:

PORT=number=80
VERBOSE=boolean=false

Once defaults and types are set, loading is a breeze:

require('env-smart').load();

console.log(`${process.env.PORT}: ${typeof process.env.PORT}`);
// 80: number

If neither value is otherwise defined, process.env would parse to:

{
  "PORT": 80,
  "VERBOSE": false
}

Process env values take precedence over the contents of a .env file, and type checking is still applied.

$ export PORT=8080 && node index.js
require('env-smart').load();
console.log(`${process.env.PORT}: ${typeof process.env.PORT}`);
// 8080: number

Using a .env file makes managing different configurations between deployments much easier:

PORT=8080
VERBOSE=TRUE

Be careful to never commit your .env file!

Options

The load() function supports a few optional parameters:

require('env-smart').load({
  directory: __dirname, // manually specify the directory to load .env files from
  encoding: 'utf8', // manually specify the encoding of the .env files
  lowercase: true, // make all keys lower case.
  // uppercase: true, // make all keys upper case
  verbose: true, // output debug information to the console
  process: false, // if set to false, don't parse the process env, only dotfiles
  inlineTypes: false, // don't allow inline type declarations in .env or .env.defaults, e.g. PORT=number=8080
  
  envFilename : '.env', //  manually specify .env file name
  envDefaultsFilename : '.env.defaults', // manually specify .env.defaults file name
  envTypesFilename : '.env.types' // manually specify .env.types file name
});

// The 'PORT' value has been re-named 'port' by including the `lowercase` option
console.log(`${process.env.port}: ${typeof process.env.port}`);

Include replace: false option to return the parsed values without replacing the contents of process.env:

const settings = require('env-smart').load({ replace: false, lowercase: true });

console.log(settings.port);

License

MIT © Jesse T Youngblood

You can’t perform that action at this time.