Enforceable environment variable contracts at runtime


4511.3.43 years ago4 years agoMinified + gzip package size for @freighthub/typed-env in KB



Enforceable environment variable contracts at runtime.


Use this library to make sure all the environment variables used in a project are valid.


To use the library, first declare a schema that consists of groups. A group is a set of related environment variables that typically share a common prefix. Groups are created using envGroup function that accepts a dictionary which contains variable names and their types, e.g.:

import * as typedEnv from '@freighthub/typed-env'

const statsd = typedEnv.envGroup({
    HOST: NonEmptyString,
    PORT: PortNumber,
    PREFIX: NonEmptyString,
}, 'STATSD')

const schema = typedEnv.envSchema({
    statsd: statsd,

In the above example statsd group will be used to load variables


The optional STATSD prefix is passed as the second parameter to envGroup. The schema is then created using envSchema function that accepts a dictionary of groups.

To validate environment variables, make sure they're set (use dotenv.config() to load .env if required). Then use loadFromEnv as follows:

const env = typedEnv.loadFromEnv(schema)

If any variables are missing or don't pass type checking, an exception will occur.


typed-env provides the following schema types:

  • Number - any number
  • Integer - integer number
  • PortNumber - integer number between 1 and 65535
  • NonEmptyString - non-empty string of any length
  • URI - URI as checked by valid-url
  • Boolean - true or false
  • Union - a collection of string literals to resctrict a variable's possible value


import * as typedEnv from '@freighthub/typed-env'

const schema = typedEnv.envSchema({
    elasticSearch: typedEnv.envGroup({
        URL: typedEnv.types.URI

const env = typedEnv.loadFromEnv(schema)

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.