Safe Environment Variables
Read environment variables in a safe way, with full TypeScript support. No more missing environment variables!
Quick Start
By default, safe-env-vars
will read environment variables from the environment as well as a .env
file. It will also throw an error by default if the environment variable you're trying to read is undefined. See the FAQ at the bottom for some helpful hints.
import { EnvironmentReader } from 'safe-env-vars';
const env = new EnvironmentReader();
const myVar = env.get(`SOME_VARIABLE`); // string
const port = env.number.get(`PORT`); // number
const optionalFlag = env.optional.boolean.get(`COOL_FEATURE_FLAG`); // boolean | undefined
Constructor Options
The following options can be passed to the constructor when instantiating the class.
Option | Default | Required | Description |
---|---|---|---|
dotEnv |
true |
- | Set to false to disable dot env functionality. |
dotEnvPath |
Current working directory | - | Specify the path to the dot env file, optional. |
Methods
An EnvironmentReader instance has the following methods. Each method takes a key
string and an optional options
dictionary. See the section on 'get method options' for the shape of options
.
➡️ env.get(key, options?)
Reads the environment variable at key
as a string
and throws an error if it doesn't exist.
➡️ env.string.get(key, options?)
Same as env.get(key, options?)
.
➡️ env.number.get(key, options?)
Reads the environment variable at key
casting to a number
and throws an error if it doesn't exist.
➡️ env.boolean.get(key, options?)
Reads the environment variable at key
casting to a boolean
and throws an error if it doesn't exist.
➡️ env.optional.get(key, options?)
Reads the environment variable at key
as a string
. Returns undefined
if the variable doesn't exist.
➡️ env.optional.string.get(key, options?)
Same as env.optional.get(key, options?)
.
➡️ env.optional.number.get(key, options?)
Reads the environment variable at key
casting to a number
. Returns undefined
if the variable doesn't exist.
➡️ env.optional.boolean.get(key, options?)
Reads the environment variable at key
casting to a boolean
. Returns undefined
if the variable doesn't exist.
Get Method Options
The following options can be passed to any .get()
method.
Option | Type | Default | Required | Description |
---|---|---|---|---|
allowEmpty |
Boolean | false |
- | Set to true if you want to allow the variable to be an empty string. |
allowedValues |
any[] | - | Pass an array of allowed values to verify against the typecast value. |
FAQ
safe-env-vars
?
What is Safe-env-vars
provides a way to read environment variables in a safe way, with full TypeScript support and typecasting to the correct data type. By default, an error is thrown if a variable is missing.
How do I load environment variables from a .env file?
Safe-env-vars
automatically reads environment variables from a .env file. To customise the path to the .env file specify the dotEnvPath
option when constructing EnvironmentReader
.
How do I disable .env functionality?
If you don't want safe-env-vars
to read from a .env file by default you can disable it by passing false
to the dotEnv
option when constructing EnvironmentReader
.
Do I need to install dotenv in my own project?
Nope. Safe-env-vars
uses dotenv internally.
How do I allow optional variables?
By default, safe-env-vars
will throw an error if an environment variable is undefined. To allow undefined variables, use any of the .get()
methods that include .optional
in the chain, e.g. env.optional.get('SOME_VARIABLE')
or env.optional.number.get('SOME_VARIABLE')
. See the section on 'methods' for the full list.
How do I allow an empty string as a variable?
By default, safe-env-vars
will throw an error if a variable exists but it's an empty string. You can change this by passing allowEmpty: true
to the options
parameter of any .get()
method.
How do I cast variables to a number/boolean type?
Use any of the .get()
methods that include a type modifier, e.g. env.number.get('SOME_VARIABLE')
or env.boolean.get('SOME_VARIABLE')
. See the section on 'methods' for the full list.
How do I verify the value of the variable is what I expect?
You can pass a list of allowed values to any .get()
method. If the value of the environment variable is not one of the allowed values at runtime, an error will be thrown.
const value = env.string.get(`SOME_STR`, { allowedValues: [`ABC`, `DEF`] }); // string, must be "ABC" or "DEF".
const value = env.number.get(`SOME_NUM`, { allowedValues: [461, 582, 923] }); // number, must be 461, 582, or 923.
const value = env.boolean.get(`SOME_BOOL`, { allowedValues: [true] }); // boolean, can only be true.