Envalid is a small library for validating and accessing environment variables in Node.js (v6.0 or later) programs, aiming to:
cleanEnv() returns a sanitized, immutable environment object, and accepts three
environment- An object containing your env vars (eg.
validators- An object that specifies the format of required vars.
options- An (optional) object, which supports the following keys:
false) If true, the output of
cleanEnvwill only contain the env vars that were specified in the
reporter- Pass in a function to override the default error handling and console output. See
lib/reporter.jsfor the default implementation.
transformer- A function used to transform the cleaned environment object before it is returned from
'.env') Path to the file that is parsed by dotenv to optionally load more env vars at runtime. Pass
nullif you want to skip
dotenvprocessing entirely and only load from
cleanEnv() will log an error message and exit if any required
env vars are missing or invalid.
const envalid =const str email json = envalidconst env = envalid// Read an environment variable, which is validated and cleaned during// and/or filtering that you specified with cleanEnv().envADMIN_EMAIL // -> 'email@example.com'// Envalid parses NODE_ENV automatically, and provides the following// shortcut (boolean) properties for checking its value:envisProduction // true if NODE_ENV === 'production'envisTest // true if NODE_ENV === 'test'envisDev // true if NODE_ENV === 'development'
For an example you can play with, clone this repo and see the
process.env only stores strings, but sometimes you want to retrieve other types
(booleans, numbers), or validate that an env var is in a specific format (JSON,
url, email address). To these ends, the following validation functions are available:
str()- Passes string values through, will ensure an value is present unless a
defaultvalue is given.
bool()- Parses env var strings
"0", "1", "true", "false", "t", "f"into booleans
num()- Parses an env var (eg.
"42", "0.23", "1e5") into a Number
email()- Ensures an env var is an email address
url()- Ensures an env var is a url with a protocol and hostname
json()- Parses an env var with
Each validation function accepts an (optional) object with the following attributes:
choices- An Array that lists the admissable parsed values for the env var.
default- A fallback value, which will be used if the env var wasn't specified. Providing a default effectively makes the env var optional.
devDefault- A fallback value to use only when
'production'. This is handy for env vars that are required for production environments, but optional for development and testing.
desc- A string that describes the env var.
example- An example value for the env var.
docs- A url that leads to more detailed documentation about the env var.
You can easily create your own validator functions with
envalid.makeValidator(). It takes
a function as its only parameter, and should either return a cleaned value, or throw if the
input is unacceptable:
const makeValidator cleanEnv =const twochars =const env =;
You can, and should, also provide a
type with your validator. This can be exposed by tools
to help other developers better understand you configuration options.
To add it, pass a string with the name as the second argument to
const makeValidator =const twochars =
By default, if any required environment variables are missing or have invalid
values, envalid will log a message and call
process.exit(1). You can override
this behavior by passing in your own function as
options.reporter. For example:
const env =
Envalid wraps the very handy dotenv package,
so if you have a
.env file in your project, envalid will read and validate the
env vars from that file as well.