env-smart
Zero-dependency library for using .env files with types and default values
env-smart
is a lightweight, zero-dependency library for loading configuration from environmental variables and .env
files in JavaScript or TypeScript. It is designed to solve two common issues with environmental variables:
- Variable types
- Default values
In both situations, logic specific to the configuration (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 declaring default values and types for all environmental variables in additional configuration files. It loads the contents of the .env
file if present, but defaults and type checking are applied to the process' env if not.
Installation
npm install env-smart
Usage
Calling .load()
populates process.env
with the contents of a .env
file in the root directory of your project, as well as the process' environmental variables.
// Modules
import env from 'env-smart';
env.load();
// CommonJS
require('env-smart').load();
console.log(process.env.PORT);
Using a .env
file to store environmental variables makes managing different configurations between deployments much easier. Example file:
PORT=8080
VERBOSE=TRUE
API_KEY=xyz
Strictly Typed Configuration
If you're using TypeScript, the config
function makes parsing strictly typed configurations simple:
import envSmart from 'env-smart';
// Define config type
export type Configuration = {
host: string;
port: number;
verbose: boolean;
};
// Transform the dictionary into a configuration type
export const config = envSmart.config<Configuration>((env) => {
// `env` is now populated from the .env file, process env, and defaults
return {
host: env.HOST,
port: env.PORT,
verbose: env.VERBOSE
};
});
// `config` is now strictly typed
console.log(`Host: ${config.host} port: ${config.port} verbose: ${config.verbose} `);
Types and Defaults
In addition to the main .env
file, env-smart
also checks for two additional optional configuration files: .env.defaults
and .env.types
.
Default values are set in the .env.defaults
file:
PORT=80
VERBOSE=FALSE
If an environmental variable is otherwise empty empty, it's value from .env.defaults
will be used.
Types are set in the .env.types
file:
PORT=number
VERBOSE=boolean
Supported types are: string
, number
, boolean
, object
and array
.
Alternatively, variable types may be declared inline 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
Process environmental variables 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
Both .env.defaults
and .env.types
should not contain any secrets, and should be committed to version control systems. Be careful to never commit the .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