A config library for TypeScript.

Downloads in past


651.5.02 years ago6 years agoMinified + gzip package size for ts-app-env in KB


A config library for TypeScript.
This is a small library for encapsulating access to an application's config.
Currently just environment variables.


The main goals are:
  1. Declare all of an application's config in a single place.
This helps understanding and maintaining an application's config vs. grepping for `process.env.FOO` calls spread throughout the codebase.
  1. Perform a simple "all of the config values are available" sanity check immediately on application boot.
This prevents an application booting and then ~seconds/minutes later blowing up because a `process.env.VERY_IMPORTANT_SETTING` is not available.


  • Loading config from disk.

This library currently doesn't try to load YAML, JSON, TOML, etc. files from disk; it's generally assumed you're running in a Node/container environment where environment variables are the primary means of configuration.
In theory the Environment type decouples ts-app-env from the actual Node/process/etc. environment, so you could provide other implementations.
You can also use something like dotenv to load files from disk into process.env and then use ts-app-env from there.


First declare your config in a class via the string, number, etc. options:
import { string, number } from 'ts-app-env';

const AppEnv = {
  PORT: number(),

  SOME_URL: string(),

And then instantiate it:
import { newConfig } from 'ts-app-env';

export const env = newConfig(AppEnv, process.env);

newConfig will fail if any non-optional config parameters are not available.
Then in the rest of your application, you can import env:
import { env } from 'env.ts';

env.SOME_URL; // already ensured to be set


The library supports both a convention of "property name == environment name" that allow succinct declaration:
const AppEnv = {
  PORT: number(),

As well as customization of each property via an options hash:
const AppEnv = {
  port: number({
    env: 'CUSTOM_ENV_NAME',
    default: 8080,
    optional: true,

  • env provides the environment name to look up; if not provided it defaults to the property name snake-cased (e.g. someThing will be looked up as SOME_THING)
  • default provides a default value to use if the environment value is not set
  • optional marks the option as optional, and will change the return type e.g. from port: number to port: number | undefined