Verification, sanatization, and type coercion for environment variables in Node.js
The env-var npm package is a utility for accessing and validating environment variables in Node.js applications. It provides a simple and consistent API for retrieving environment variables, ensuring they meet specified criteria, and handling default values.
Accessing Environment Variables
This feature allows you to access environment variables and convert them to the desired type. In this example, the 'PORT' environment variable is retrieved and converted to a positive integer.
const env = require('env-var');
const port = env.get('PORT').asIntPositive();
console.log(`Server running on port: ${port}`);Default Values
This feature allows you to specify default values for environment variables. If the 'HOST' environment variable is not set, it defaults to 'localhost'.
const env = require('env-var');
const host = env.get('HOST').default('localhost').asString();
console.log(`Server running on host: ${host}`);Validation
This feature ensures that certain environment variables are set and meet specified criteria. In this example, the 'API_KEY' environment variable is required and must be a string.
const env = require('env-var');
const apiKey = env.get('API_KEY').required().asString();
console.log(`API Key: ${apiKey}`);Custom Validators
This feature allows you to define custom validation logic for environment variables. In this example, the 'CUSTOM_VAR' environment variable must start with 'custom-'.
const env = require('env-var');
const customValidator = (value) => value.startsWith('custom-');
const customVar = env.get('CUSTOM_VAR').required().asString().validate(customValidator);
console.log(`Custom Var: ${customVar}`);dotenv is a popular package for loading environment variables from a .env file into process.env. It does not provide validation or type conversion features like env-var, but it is widely used for managing environment variables in development.
joi is a powerful schema description language and data validator for JavaScript. While it is not specifically designed for environment variables, it can be used to validate them. It offers more complex validation rules compared to env-var.
convict is a configuration management tool for Node.js that allows you to define a schema for your configuration, including environment variables. It provides validation and default values, similar to env-var, but also supports nested configurations and different configuration sources.
Verification, sanitization, and type coercion for environment variables in
Node.js. Supports TypeScript!
Note: env-var requires Node version 8 or later.
npm install env-var --save
yarn add env-var
In the example below we read the environment variable DB_PASSWORD and call some functions to verify it satisfies our program's needs.
const env = require('env-var');
// Or using import syntax:
// import * as env from 'env-var'
const PASSWORD = env.get('DB_PASSWORD')
// Throws an error if the DB_PASSWORD variable is not set (optional)
.required()
// Decode DB_PASSWORD from base64 to a utf8 string (optional)
.convertFromBase64()
// Call asString (or other APIs) to get the variable value (required)
.asString();
// Read in a port (checks that PORT is in the range 0 to 65535)
// Alternatively, use amdefault value of 5432 if PORT is not defined
const PORT = env.get('PORT').default('5432').asPortNumber()
import * as env from 'env-var';
// Read a PORT environment variable and ensure it's a positive integer.
// An EnvVarError will be thrown if the variable is not set, or if it
// is not a positive integer.
const PORT: number = env.get('PORT').required().asIntPositive();
There is no tight coupling between env-var
dotenv. Just npm install dotenv and
use it whatever way you're used to. This loose coupling is a good thing since
it reduces package bloat - only install what you need!
You can use dotenv with env-var via a require() calls in your code or
preloading it with the --require or -r flag in the node CLI.
Both examples below assume you have a .env file in your repository and it
contains a line similar to MY_VAR=a-string-value!.
This is per the default usage described by dotenv's README.
// Read in the .env file
require('dotenv').config()
// Read the MY_VAR entry that dotenv created
const env = require('env-var')
const myVar = env.get('MY_VAR').asString()
This is per the preload section
of the dotenv README. Run the following code by using the
node -r dotenv/config your_script.js command.
// This is just a regular node script, but we started it using the command
// "node -r dotenv/config your_script.js" via the terminal. This tells node
// to load our variables using dotenv before running the rest of our script!
// Read the MY_VAR entry that dotenv created
const env = require('env-var')
const myVar = env.get('MY_VAR').asString()
This function is useful if you're not in a typical Node.js environment, or for
testing. It allows you to generate an env-var instance that reads from the
given values instead of the default process.env Object.
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()
When calling env.from() you can also pass an optional parameter containing
custom accessors that will be attached to any variables returned by that
env-var instance. This feature is explained in the
extraAccessors section of these docs.
This function has two behaviours:
Examples:
const env = require('env-var')
// #1 - Read the requested variable and parse it to a positive integer
const limit = env.get('MAX_CONNECTIONS').asIntPositive()
// #2 - Returns the entire process.env object
const allVars = env.get()
A variable is returned by calling env.get(varname). It exposes the following
functions to validate and access the underlying value, set a default, or set
an example value:
Allows a developer to provide an example of a valid value for the environment
variable. If the variable is not set (and required() was called), or the
variable is set incorrectly this will be included in error output to help
developers diagnose the error.
For example:
const env = require('env-var')
const ADMIN_EMAIL = env.get('ADMIN_EMAIL')
.required()
.example('admin@example.com')
.asString()
If ADMIN_EMAIL was not set this code would throw an error similar to that below to help a developer diagnose the issue:
env-var: "ADMIN_EMAIL" is a required variable, but it was not set. An example
of a valid value would be "admin@example.com"
Allows a default value to be provided for use if the desired environment variable is not set in the program environment.
Example:
const env = require('env-var')
// Use POOL_SIZE if set, else use a value of 10
const POOL_SIZE = env.get('POOL_SIZE').default('10').asIntPositive()
Ensure the variable is set on process.env. If the variable is not set, or is
set to an empty value, this function will cause an EnvVarError to be thrown
when you attempt to read the value using asString or a similar function.
The required() check can be bypassed by passing false, i.e
required(false)
Example:
const env = require('env-var')
// Get the value of NODE_ENV as a string. Could be undefined since we're
// not calling required() before asString()
const NODE_ENV = env.get('NODE_ENV').asString()
// Read PORT variable and ensure it's in a valid port range. If it's not in
// valid port ranges, not set, or empty an EnvVarError will be thrown
const PORT = env.get('PORT').required().asPortNumber()
// If mode is production then this is required
const SECRET = env.get('SECRET').required(NODE_ENV === 'production').asString()
It's a common need to set an environment variable in base64 format. This function can be used to decode a base64 environment variable to UTF8.
For example if we run the script script below, using the command DB_PASSWORD= $(echo -n 'secret_password' | base64) node, we'd get the following results:
console.log(process.env.DB_PASSWORD) // prints "c2VjcmV0X3Bhc3N3b3Jk"
// dbpass will contain the converted value of "secret_password"
const dbpass = env.get('DB_PASSWORD').convertFromBase64().asString()
Converts the value of the environment variable to an integer and verifies it's within the valid port range of 0-65535. As a result well known ports are considered valid by this function.
Converts the value to a string, and matches against the list of valid values. If the value is not valid, an error will be raised describing valid input.
Attempt to parse the variable to an integer. Throws an exception if parsing fails. This is a strict check, meaning that if the process.env value is "1.2", an exception will be raised rather than rounding up/down.
Performs the same task as asInt(), but also verifies that the number is positive (greater than zero).
Performs the same task as asInt(), but also verifies that the number is negative (less than zero).
Attempt to parse the variable to a float. Throws an exception if parsing fails.
Performs the same task as asFloat(), but also verifies that the number is positive (greater than zero).
Performs the same task as asFloat(), but also verifies that the number is negative (less than zero).
Return the variable value as a String. Throws an exception if value is not a String. It's highly unlikely that a variable will not be a String since all process.env entries you set in bash are Strings by default.
Attempt to parse the variable to a Boolean. Throws an exception if parsing fails. The var must be set to either "true", "false" (upper or lowercase), 0 or 1 to succeed.
Attempt to parse the variable to a Boolean. Throws an exception if parsing fails. The var must be set to either "true" or "false" (upper or lowercase) to succeed.
Attempt to parse the variable to a JSON Object or Array. Throws an exception if parsing fails.
The same as asJson but checks that the data is a JSON Array, e.g [1,2].
The same as asJson but checks that the data is a JSON Object, e.g {a: 1}.
Reads an environment variable as a string, then splits it on each occurence of the specified delimiter. By default a comma is used as the delimiter. For example a var set to "1,2,3" would become ['1', '2', '3']. Example outputs for specific values are:
MY_ARRAY='' results in []MY_ARRAY='1' results in ['1']MY_ARRAY='1,2,3' results in ['1', '2', '3']Verifies that the variable is a valid URL string and returns the validated string. The validation is performed by passing the URL string to the Node.js URL Constructor.
Verifies that the variable is a valid URL string using the same method as
asUrlString(), but instead returns the resulting URL instance. For details
see the Node.js URL docs.
This is the error class used to represent errors raised by this module. Sample usage:
const env = require('env-var')
let value = null
try {
// will throw if you have not set this variable
value = env.get('MISSING_VARIABLE').required().asString()
// if catch error is set, we'll end up throwing here instead
throw new Error('some other error')
} catch (e) {
if (e instanceof env.EnvVarError) {
console.log('we got an env-var error', e)
} else {
console.log('we got some error that wasn\'t an env-var error', e)
}
}
const env = require('env-var');
// Normally these would be set using "export VARNAME" or similar in bash
process.env.STRING = 'test';
process.env.INTEGER = '12';
process.env.BOOL = 'false';
process.env.JSON = '{"key":"value"}';
process.env.COMMA_ARRAY = '1,2,3';
process.env.DASH_ARRAY = '1-2-3';
// The entire process.env object
const allVars = env.get();
// Returns a string. Throws an exception if not set or empty
const stringVar = env.get('STRING').required().asString();
// Returns an int, undefined if not set, or throws if set to a non integer value
const intVar = env.get('INTEGER').asInt();
// Return a float, or 23.2 if not set
const floatVar = env.get('FLOAT').default('23.2').asFloat();
// Return a Boolean. Throws an exception if not set or parsing fails
const boolVar = env.get('BOOL').required().asBool();
// Returns a JSON Object, undefined if not set, or throws if set to invalid JSON
const jsonVar = env.get('JSON').asJson();
// Returns an array if defined, or undefined if not set
const commaArray = env.get('COMMA_ARRAY').asArray();
// Returns an array if defined, or undefined if not set
const commaArray = env.get('DASH_ARRAY').asArray('-');
// Returns the enum value if it's one of dev, test, or live
const enumVal = env.get('ENVIRONMENT').asEnum(['dev', 'test', 'live'])
When calling from() you can also pass an optional parameter containing
additional accessors that will be attached to any variables gotten by that
env-var instance.
Accessor functions must accept at least one argument:
{*} value: The value that the accessor should process.Important: Do not assume that value is a string!
Example:
const { from } = require('env-var')
// Environment variable that we will use for this example:
process.env.ADMIN = 'admin@example.com'
// Add an accessor named 'asEmail' that verifies that the value is a
// valid-looking email address.
const env = from(process.env, {
asEmail: (value) => {
const split = String(value).split('@')
// Validating email addresses is hard.
if (split.length !== 2) {
throw new Error('must contain exactly one "@"')
}
return value
}
})
// We specified 'asEmail' as the name for the accessor above, so now
// we can call `asEmail()` like any other accessor.
let validEmail = env.get('ADMIN').asEmail()
The accessor function may accept additional arguments if desired; these must be provided explicitly when the accessor is invoked.
For example, we can modify the asEmail() accessor from above so that it
optionally verifies the domain of the email address:
const { from } = require('env-var')
// Environment variable that we will use for this example:
process.env.ADMIN = 'admin@example.com'
// Add an accessor named 'asEmail' that verifies that the value is a
// valid-looking email address.
//
// Note that the accessor function also accepts an optional second
// parameter `requiredDomain` which can be provided when the accessor is
// invoked (see below).
const env = from(process.env, {
asEmail: (value, requiredDomain) => {
const split = String(value).split('@')
// Validating email addresses is hard.
if (split.length !== 2) {
throw new Error('must contain exactly one "@"')
}
if (requiredDomain && (split[1] !== requiredDomain)) {
throw new Error(`must end with @${requiredDomain}`)
}
return value
}
})
// We specified 'asEmail' as the name for the accessor above, so now
// we can call `asEmail()` like any other accessor.
//
// `env-var` will provide the first argument for the accessor function
// (`value`), but we declared a second argument `requiredDomain`, which
// we can provide when we invoke the accessor.
// Calling the accessor without additional parameters accepts an email
// address with any domain.
let validEmail = env.get('ADMIN').asEmail()
// If we specify a parameter, then the email address must end with the
// domain we specified.
let invalidEmail = env.get('ADMIN').asEmail('github.com')
This feature is also available for TypeScript users. The ExtensionFn type is
exposed to help in the creation of these new accessors.
import { from, ExtensionFn, EnvVarError } from 'env-var'
// Environment variable that we will use for this example:
process.env.ADMIN = 'admin@example.com'
const asEmail: ExtensionFn<string> = (value) => {
const split = String(value).split('@')
// Validating email addresses is hard.
if (split.length !== 2) {
throw new Error('must contain exactly one "@"')
}
return value
}
const env = from(process.env, {
asEmail
})
// Returns the email string if it's valid, otherwise it will throw
env.get('ADMIN').asEmail()
Contributions are welcomed. If you'd like to discuss an idea open an issue, or a PR with an initial implementation.
If you want to add a new global accessor add a file to lib/accessors, with
the name of the type e.g add a file named number-zero.js into that folder
and populate it with code following this structure:
/**
* Validate that the environment value is an integer and equals zero.
* This is a strange example, but hopefully demonstrates the idea.
* @param {String} environmentValue this is the string from process.env
*/
module.exports = function numberZero (environmentValue) {
// Your custom code should go here...below code is an example
const val = parseInt(environmentValue)
if (val === 0) {
return ret;
} else {
throw new Error('should be zero')
}
}
Next update the accessors Object in getVariableAccessors() in
lib/variable.js to include your new module. The naming convention should be of
the format "asTypeSubtype", so for our number-zero example it would be done
like so:
asNumberZero: generateAccessor(container, varName, defValue, require('./accessors/number-zero')),
Once you've done that, add some unit tests and use it like so:
// Uses your new function to ensure the SOME_NUMBER is the integer 0
env.get('SOME_NUMBER').asNumberZero()
6.0.0 (12/02/2020)
example(string) function.default(string) function.required() until an accessor such as asString() is invoked.required() was undefined on a IPresentVariable.Migration from 5.x to 6.0.0 should be smooth. Change any instance of
env.get(target, default) to env.get(target).default(default). For example:
// Old 5.x code
const emailAddr = env.get('EMAIL_ADDR', 'admin@example.com').asString()
// New 6.x compatible code
const emailAddr = env.get('EMAIL_ADDR').default('admin@example.com').asString()
FAQs
Verification, sanitization, and type coercion for environment variables in Node.js
The npm package env-var receives a total of 227,919 weekly downloads. As such, env-var popularity was classified as popular.
We found that env-var demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket is tracking a new trend where malicious actors are now exploiting the popularity of LLM research to spread malware through seemingly useful open source packages.
Security News
Research
Noxia, a new dark web bulletproof host, offers dirt cheap servers for Python, Node.js, Go, and Rust, enabling cybercriminals to distribute malware and execute supply chain attacks.
Company News
Socket safeguards companies from software supply chain attacks by detecting and preventing threats in open source code and empowering developers to secure their applications and critical services against malware and other security risks.