How to Validate Environment Variables in TypeScript (and Why You Should)

Every developer has a story about a .env file causing a production outage. Maybe it was a missing DATABASE_URL that silently defaulted to undefined. Maybe NODE_ENV was set to staging instead of production, and staging API keys leaked into production traffic. Or perhaps a port number was accidentally typed as a string, and the server crashed with a cryptic type error.

Environment variables are the most common way to configure applications, but they have no built-in safety net. A typo, a missing value, or a misconfigured variable can reach production without a single warning — until your monitoring dashboard turns red.

In this tutorial, you'll learn how to define a schema for your environment variables, validate them automatically, generate TypeScript types from your schema, and catch configuration errors before they reach production.

The Problem: .env Files Have No Guardrails

Consider a typical .env file:

PORT=3000
DATABASE_URL=postgresql://localhost:5432/myapp
NODE_ENV=development
API_KEY=

Now consider what happens when:

• PORT accidentally gets set to "abc" — your server fails to bind
• NODE_ENV is set to "staging" — your production environment uses staging credentials
• API_KEY is blank — third-party API calls fail with 401s
• DATABASE_URL uses http:// instead of postgresql:// — the connection pool silently fails

Without validation, each of these scenarios causes a runtime failure. With validation, they're caught in CI before deployment.

Introducing Schema-Based Validation

The fix is simple: define what each variable should look like, then check your .env file against that schema before anything runs.

A schema for the variables above might look like:

{
  "vars": {
    "PORT": {
      "type": "number",
      "required": true,
      "format": "port",
      "default": 3000
    },
    "DATABASE_URL": {
      "type": "string",
      "required": true,
      "format": "url"
    },
    "NODE_ENV": {
      "type": "string",
      "enum": ["development", "production", "test"],
      "default": "development"
    },
    "API_KEY": {
      "type": "string",
      "required": true
    }
  }
}

This schema declares:

• PORT must be a number, must be a valid port (1–65535), and defaults to 3000
• DATABASE_URL must be a string, must be a valid URL, and is required
• NODE_ENV can only be one of three values and defaults to development
• API_KEY must be a string and is required

Validating Your .env File

The tool we'll use is env-haven, a zero-dependency CLI that validates .env files against a JSON schema. Install it with a single command:

npx env-haven

Save the schema above as checkmyenv.config.json in your project root. Then run:

env-haven

If all variables are valid, you'll see:

env-haven — Environment Variable Validation

  ✓ PORT = 3000
  ✓ DATABASE_URL = postgresql://localhost:5432/myapp
  ✓ NODE_ENV = development
  ✓ API_KEY = sk-abc123

PASS  4 vars — 4 passed, 0 failed

If something is wrong, you get clear error messages:

env-haven — Environment Variable Validation

  ✗ PORT = abc
    │ "PORT" must be a number (got "abc")
    │ "PORT" must be a valid port (1-65535, got "abc")
  ✗ NODE_ENV = staging
    │ "NODE_ENV" must be one of: development, production, test (got "staging")
  ✗ API_KEY = (not set)
    │ Missing required variable "API_KEY"

FAIL  4 vars — 1 passed, 3 failed

The exit code is 1 on failure, which means you can plug this into any CI pipeline:

# .github/workflows/validate-env.yml
name: Validate environment config
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx env-haven

This checks the default .env file. For staging or production, you can validate against different .env files by copying them into place before running the check.

Going Further: Generators

Typing out your schema is useful, but env-haven can do more.

Generate a .env.example

Keep your .env.example in sync with your schema automatically:

env-haven generate

This produces:

env-haven: Generated .env.example

The output file has every variable listed with its default value and a comment explaining what it's for. Required variables are marked explicitly:

# Server port
# PORT=3000
# ^^^ REQUIRED: uncomment and set this value

# PostgreSQL connection string
DATABASE_URL=

# Environment name
# NODE_ENV=development

# API authentication key
API_KEY=

Required variables are uncommented so they fail loudly if unset. Optional ones are commented out with their defaults filled in. This makes onboarding new team members trivial — they can copy .env.example to .env, uncomment the variables they need, and go.

Generate TypeScript Types

If you access environment variables through process.env, you've probably written something like this:

const port = parseInt(process.env.PORT || "3000", 10);

This works, but it's verbose, error-prone, and doesn't scale. A better approach is to define a typed interface for your environment. env-haven can generate it for you:

env-haven types

This creates an env.d.ts file:

// Auto-generated by env-haven

export interface Env {
  readonly PORT: number;
  readonly DATABASE_URL: string;
  readonly NODE_ENV: string;
  readonly API_KEY: string;
}

Now you can use it in your application:

import type { Env } from "./env";

function getEnv(): Env {
  return {
    PORT: parseInt(process.env.PORT!, 10),
    DATABASE_URL: process.env.DATABASE_URL!,
    NODE_ENV: process.env.NODE_ENV!,
    API_KEY: process.env.API_KEY!,
  };
}

Pair this with a validation step in your build, and you get compile-time confidence that your environment is correctly configured.

Schema Reference

Here's every validation rule available:

Rule	Example	What it checks
type	"number", "boolean", "integer"	Value has the correct JavaScript type
required	true / false	Value is present (unless a default is set)
default	3000	Fallback value when the variable is not set
format	"url", "email", "port"	Value matches an expected format
enum	["dev", "prod"]	Value is in the allow-list
pattern	"^sk-"	Value matches a regular expression
min	1	Minimum length (strings) or value (numbers)
max	65535	Maximum length (strings) or value (numbers)

Supported formats include: url, email, port, uuid, hostname, path, and regexp.

Integrating With Your Workflow

The most effective setup is three steps:

1. Commit your schema — checkmyenv.config.json lives in version control alongside your code
2. Validate in CI — run npx env-haven as a lint step in every pull request
3. Generate on change — run env-haven generate whenever the schema changes, and commit the updated .env.example

This creates a virtuous cycle: the schema is the source of truth, the .env.example is always accurate, and bad configuration never reaches production.

Conclusion

Environment variable validation is one of those small investments that pays for itself the first time it catches a bug. A schema takes five minutes to write, but it prevents the kind of production incidents that take hours to debug.

The tool we used, env-haven, is open source (MIT), has zero dependencies, and runs in under 100ms. Try it on your next project:

npx env-haven

Your future self — and your on-call rotation — will thank you.