env-var

For TypeScript users, env-var provides type safety. When using accessors like .asIntPositive(), the returned value is typed accordingly (e.g., number). If the variable is missing or fails validation, an EnvVarError is thrown.

import * as env from 'env-var';

// Read a PORT environment variable and ensure it's a positive integer.
const PORT: number = env.get('PORT').required().asIntPositive();

Web bundlers like Vite often do not expose process.env and instead use specific conventions (like import.meta.env). To use env-var in these environments, use the from() function to map your bundler's environment object into an env-var instance.

import { from } from 'env-var'

const env = from({
  BASE_URL: import.meta.env.BASE_URL,
  VITE_CUSTOM_VARIABLE: import.meta.env.CUSTOM_VARIABLE
})

You can provide a custom logging function to env-var to control how logs are handled (e.g., filtering by log level or using a specific logging library like pino).

When initializing the environment with from(source, defaults, logger), the logger function receives two arguments:

1. varname: The name of the environment variable being read (e.g., "API_KEY").
2. str: The log message (e.g., "verifying variable value is not empty").

const pino = require('pino')()
const customLogger = (varname, str) => {
  // varname is the name of the variable being read, e.g "API_KEY"
  // str is the log message, e.g "verifying variable value is not empty"
  pino.trace(`env-var log (${varname}): ${str}`)
}

const { from } =  require('env-var')
const env = from(process.env, {}, customLogger)

const API_KEY = env.get('API_KEY').required().asString()

In Node.js, you can use env.get() to retrieve environment variables. You can chain methods to enforce requirements (like .required()), perform transformations (like .convertFromBase64()), or provide defaults (like .default()), and finally call an accessor (like .asString() or .asPortNumber()) to get the coerced value.

const env = require('env-var');

// Throws error if DB_PASSWORD is missing, decodes from base64, and returns string
const PASSWORD = env.get('DB_PASSWORD')
  .required()
  .convertFromBase64()
  .asString();

// Uses default '5432' if PORT is not defined, and validates it is a port number
const PORT = env.get('PORT').default('5432').asPortNumber();

Logging is disabled by default to prevent accidental leakage of secrets. To enable it, you must create an instance using from() and pass a logger.

Built-in Logger: If you use the built-in logger, it will only print logs when NODE_ENV is not set to prod or production.

const { from, logger } =  require('env-var')
const env = from(process.env, {}, logger)

const API_KEY = env.get('API_KEY').required().asString()

You can install env-var using either npm or yarn to add verification, sanitization, and type coercion for environment variables to your project.

npm install env-var
# or
yarn add env-var

You can use dotenv to load environment variables from a .env file before accessing them with env-var. There are two primary ways to do this:

1. Load via require()

Call require('dotenv').config() at the entry point of your application to populate process.env.

2. Preload via CLI

Use the Node.js --require (or -r) flag to load dotenv/config before your script executes. This avoids adding manual configuration code to your source files.

Pre-requisite: Ensure you have a .env file in your repository containing your variables (e.g., MY_VAR=a-string-value!).

// Option 1: Load via require()
require('dotenv').config()
const env = require('env-var')
const myVar = env.get('MY_VAR').asString()

To load environment variables from a .env file without modifying your code, run your Node.js script using the -r flag to preload dotenv/config.

node -r dotenv/config your_script.js

The env.accessors object exposes all the parsing and validation logic as standalone functions. These accept a String as their first argument. This is useful for building custom accessors or validating strings manually without using the env.get() chain.

const env = require('env-var')

// Validate that a string is JSON directly
const myJsonDirectAccessor = env.accessors.asJson(process.env.SOME_JSON)

The get() function has two modes:

1. Read a specific variable: Pass a string argument (the variable name) to return a variable object for that key.
2. Read the entire environment: Pass no arguments to return the entire environment object (e.g., process.env).

const env = require('env-var')

// Read a specific variable
const limit = env.get('MAX_CONNECTIONS').asIntPositive()

// Returns the entire process.env object
const allVars = env.get()

Use from(values, extraAccessors, logger) to create an env-var instance that reads from a provided object instead of the default process.env. This is useful for testing or non-Node.js environments.

You can also provide a custom logger function to log validation messages. The logger signature is (varname, str), where varname is the variable name and str is the log message.

const env = require('env-var').from({
  API_BASE_URL: 'https://my.api.com/'
})

// apiUrl will be 'https://my.api.com/'
const apiUrl = env.get('API_BASE_URL').asUrlString()