ts-dotenv

Strongly-typed Node.js environment variables from .env and process.env.

Motivation

Load environment variables from a .env file for development, but deploy to an environment that injects them directly (on process.env) with no logic needed to differentiate dev from prod. Values from disk are merged with the process environment (you decide whether process.env or .env takes precedence), validated against a simple schema, and coerced to the appropriate types.

ts-dotenv maintains dev/prod parity by not caring whether variables come from .env or process.env, as long as they’re all present and the correct types. Otherwise, it fails fast, so your alarms should start going off and/or your rolling releases will abort. The thrown error details which variables are missing or have the wrong types.

Caution: Be careful removing variables from your prod environment; be sure to first remove them from the schema, otherwise your server won’t boot and it will have nothing to roll back to. (Or you could catch the error ts-dotenv throws, and do your own logging or alerts, but you’ll lose automatic protection from pushing out builds with missing variables. It’s a trade-off.)

Usage

# Comments are supported
TRACING=true
PORT=3000
NODE_ENV=production
APP_NAME=test-app
BASE_URL=https://api.example.com
#BASE_URL=https://development-api.example.com
EXTRA=true

import { strict as assert } from 'assert';
import { load } from 'ts-dotenv';

const env = load({
    TRACING: Boolean,
    PORT: Number,
    APP_NAME: /^[-a-z]+$/,
    BASE_URL: String,
    NODE_ENV: [
        'production' as const,
        'development' as const,
    ],
});

assert.ok(env.TRACING === true);
assert.ok(env.PORT === 3000);
assert.ok(env.APP_NAME === 'test-app');
assert.ok(env.NODE_ENV === 'production');
assert.ok(env.BASE_URL === 'https://api.example.com');
assert.ok(env.EXTRA === undefined);

Note:

• Number only supports integers
• Only string unions are supported
• Use as const with string unions, to ensure a proper resulting environment type

Optionals & defaults

Optional fields and default values can be defined with an extended schema specifier; for example:

const schema = {
    TRACING: {
        type: Boolean,
        optional: true,
    },
    NODE_ENV: {
        type: String,
        default: 'local',
    }
} as const;

Boot

Run ts-dotenv from your app’s entry, to ensure variables are loaded before you wire up services and start serving requests. The following pattern makes for easy, type-safe consumption of variables throughout your app:

index.ts

import { loadEnv } from './env';

loadEnv(); // Executed synchronously before the rest of your app loads

require('./server'); // Your server’s actual entry

env.ts

import { EnvType, load } from 'ts-dotenv';

export type Env = EnvType<typeof schema>;

export const schema = {
    NODE_ENV: String,
};

export let env: Env;

export function loadEnv(): void {
    env = load(schema);
}

example-module.ts

import { env } from './env';

if (env.NODE_ENV === 'production') {
    // ...
}

Options

By default:

• Values in process.env take precedence
• .env is the expected file name, loaded from the working directory

Change this through options:

import { resolve } from 'path';
import { load } from 'ts-dotenv';
const env = load(schema, 'lib/.env');

import { resolve } from 'path';
import { load } from 'ts-dotenv';

const env = load(schema, {
    path: resolve(__dirname, '.env'),
    encoding: 'iso-8859-1',
    overrideProcessEnv: true,
});

Improvements

• Add support for floats
• Add support for number union types

Acknowledgements

This was inspired by dotenv and dotenv-extended, but written for first-class use in a TypeScript project.