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.

npm install env-smart

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

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} `);

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.

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);

MIT © Jesse T Youngblood