Envalid is a small library for validating and accessing
environment variables in Node.js programs
Envalid is a small library for validating and accessing environment variables in Node.js programs, aiming to:
- Ensure that your program only runs when all of its environment dependencies are met
- Give you executable documentation about the environment your program expects to run in
- Give you an immutable API for your environment variables, so they don't change from under you while the program is running
- Type-safe: written completely in TypeScript, with great support for inference
- Light: no dependencies besides tslib
- Modular: customize behavior with custom validators, middleware, and reporters
cleanEnv() returns a sanitized, immutable environment object, and accepts three
positional arguments:
environment- An object containing your env vars (eg.process.env)validators- An object that specifies the format of required vars.options- An (optional) object, which supports the following key:reporter- Pass in a function to override the default error handling and console output. Seesrc/reporter.tsfor the default implementation.
By default, cleanEnv() will log an error message and exit (in Node) or throw (in browser) if any required
env vars are missing or invalid. You can override this behavior by writing your own reporter.
import { cleanEnv, str, email, json } from 'envalid'
const env = cleanEnv(process.env, {
API_KEY: str(),
ADMIN_EMAIL: email({ default: '[email protected]' }),
EMAIL_CONFIG_JSON: json({ desc: 'Additional email parameters' }),
NODE_ENV: str({ choices: ['development', 'test', 'production', 'staging'] }),
})
// Read an environment variable, which is validated and cleaned during
// and/or filtering that you specified with cleanEnv().
env.ADMIN_EMAIL // -> '[email protected]'
// Envalid checks for NODE_ENV automatically, and provides the following
// shortcut (boolean) properties for checking its value:
env.isProduction // true if NODE_ENV === 'production'
env.isTest // true if NODE_ENV === 'test'
env.isDev // true if NODE_ENV === 'development'For an example you can play with, clone this repo and see the example/ directory.
git clone https://github.com/af/envalid
cd envalid
yarn prepare
node example/server.js
Node's 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 a value is present unless adefaultvalue is given. Note that an empty string is considered a valid value - if this is undesirable you can easily create your own validator (see below)bool()- Parses env var strings"1", "0", "true", "false", "t", "f", "yes", "no", "on", "off"into booleansnum()- Parses an env var (eg."42", "0.23", "1e5") into a Numberemail()- Ensures an env var is an email addresshost()- Ensures an env var is either a domain name or an ip address (v4 or v6)port()- Ensures an env var is a TCP port (1-65535)url()- Ensures an env var is a URL with a protocol and hostnamejson()- Parses an env var withJSON.parse
Each validation function accepts an (optional) object with the following attributes:
choices- An Array that lists the admissible parsed values for the env var.default- A fallback value, which will be present in the output if the env var wasn't specified. Providing a default effectively makes the env var optional. Note thatdefaultvalues are not passed through validation logic, they are default output values.devDefault- A fallback value to use only whenNODE_ENVis explicitly set and not'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.requiredWhen- A function (env -> boolean) specifying when this env var is required. Use With default: undefined (optional value).
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:
import { makeValidator, cleanEnv } from 'envalid'
const twochars = makeValidator((x) => {
if (/^[A-Za-z]{2}$/.test(x)) return x.toUpperCase()
else throw new Error('Expected two letters')
})
const env = cleanEnv(process.env, {
INITIALS: twochars(),
})You can use either one of makeValidator, makeExactValidator and makeStructuredValidator
depending on your use case.
This validator has the output narrowed down to a subtype of BaseT (e.g. str).
Example of a custom integer validator:
const int = makeValidator<number>((input: string) => {
const coerced = parseInt(input, 10)
if (Number.isNaN(coerced)) throw new EnvError(`Invalid integer input: "${input}"`)
return coerced
})
const MAX_RETRIES = int({ choices: [1, 2, 3, 4] })
// Narrows down output type to '1 | 2 | 3 | 4' which is a subtype of 'number'This validator has the output widened to T (e.g. bool). To understand the difference
with makeValidator, let's use it in the same scenario:
const int = makeExactValidator<number>((input: string) => {
const coerced = parseInt(input, 10)
if (Number.isNaN(coerced)) throw new EnvError(`Invalid integer input: "${input}"`)
return coerced
})
const MAX_RETRIES = int({ choices: [1, 2, 3, 4] })
// Output type is 'number'As you can see in this instance, the output type is exactly number, the parameter type of
makeExactValidator. Also note that here, int is not parametrizable.
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 = cleanEnv(process.env, myValidators, {
reporter: ({ errors, env }) => {
emailSiteAdmins('Invalid env vars: ' + Object.keys(errors))
},
})Additionally, Envalid exposes EnvError and EnvMissingError, which can be checked in case specific error handling is desired:
const env = cleanEnv(process.env, myValidators, {
reporter: ({ errors, env }) => {
for (const [envVar, err] of Object.entries(errors)) {
if (err instanceof envalid.EnvError) {
...
} else if (err instanceof envalid.EnvMissingError) {
...
} else {
...
}
}
}
})In addition to cleanEnv(), as of v7 there is a new customCleanEnv() function,
which allows you to completely replace the processing that Envalid applies after applying
validations. You can use this custom escape hatch to transform the output however you wish.
customCleanEnv() uses the same API as cleanEnv(), but with an additional applyMiddleware
argument required in the third position:
applyMiddleware- A function that can modify the env object after it's validated and cleaned. Envalid ships (and exports) its own default middleware (see src/middleware.ts), which you can mix and match with your own custom logic to get the behavior you desire.
The testOnly helper function is available for setting a default value for an env var only when NODE_ENV=test. It is recommended to use this function along with devDefault. For example:
const env = cleanEnv(process.env, {
SOME_VAR: envalid.str({ devDefault: testOnly('myTestValue') }),
})For more context see this issue.
Since by default Envalid's output is wrapped in a Proxy, structuredClone will not work on it. See #177.
-
dotenv is a very handy tool for loading env vars from
.envfiles. It was previously used as a dependency of Envalid. To use them together, simply callrequire('dotenv').config()before you passprocess.envto yourenvalid.cleanEnv(). -
react-native-config can be useful for React Native projects for reading env vars from a
.envfile -
fastify-envalid is a wrapper for using Envalid within Fastify
-
nestjs-envalid is a wrapper for using Envalid with NestJS
-
nuxt-envalid is a wrapper for using Envalid with NuxtJS