DEV Community

Cover image for TypeScript Environment Variables: The Complete Guide
Odejobi Abiola Samuel
Odejobi Abiola Samuel

Posted on

TypeScript Environment Variables: The Complete Guide

#node #typescript #javascript #tutorial

TypeScript Environment Variables: The Complete Guide

What Are Environment Variables?

Environment variables are key-value pairs your operating system or runtime passes into a process. Think of them as external configuration that stays outside your code. You don't want to hardcode a database URL or an API key — env vars let you change those values between dev, staging, and production without touching a single source file.

How Node.js Exposes Them

Node.js makes every env var available through process.env. It's a plain object where each key is a variable name and each value is a string — or undefined if the variable doesn't exist.

console.log(process.env.PORT)   // "3000" or undefined
console.log(process.env.NODE_ENV) // "development" or undefined
Enter fullscreen mode Exit fullscreen mode

That's it. One global object. Simple, but also the source of most of the pain we'll talk about.

The TypeScript Problem

Here's the issue: process.env is typed as Record<string, string | undefined>. That means every single lookup returns string | undefined, even for variables you know exist. TypeScript can't help you catch typos, missing vars, or type mismatches at compile time.

const port = process.env.PORT
//    ^? string | undefined
Enter fullscreen mode Exit fullscreen mode

You can't ship this without validation unless you enjoy runtime crashes.

Pattern 1: Direct Access with Fallbacks

The simplest approach. Use nullish coalescing to provide defaults.

const PORT = Number(process.env.PORT ?? "3000")
const NODE_ENV = process.env.NODE_ENV ?? "development"
Enter fullscreen mode Exit fullscreen mode

You'll see this in a ton of codebases. It's fast to write and works fine for small projects. The downside? Every file that reads env vars duplicates this logic, and there's no central place to see every variable your app expects.

Pattern 2: Manual Validation Function

A step up. Centralize your env access in one file with a helper that throws on missing required vars.

function getEnv(key: string, fallback?: string): string {
  const value = process.env[key] ?? fallback
  if (value === undefined) {
    throw new Error(`Missing required env var: ${key}`)
  }
  return value
}

export const config = {
  port: Number(getEnv("PORT", "3000")),
  nodeEnv: getEnv("NODE_ENV", "development"),
  databaseUrl: getEnv("DATABASE_URL"),
}
Enter fullscreen mode Exit fullscreen mode

Better. Now all vars live in one place. But you're still manually parsing types, and error messages are whatever you decide to write. Add ten more vars and this file starts to feel heavy.

Pattern 3: Schema-Based Validation

This is where libraries come in. Instead of writing parsing logic yourself, you declare a schema and let the library handle validation, typing, and error formatting.

Using CtroEnv (one option among several — Zod also works well for this):

import { defineEnv, string, number } from "@ctroenv/core"

const env = defineEnv({
  PORT: number().port().default(3000),
  DATABASE_URL: string().url(),
  NODE_ENV: string().optional(),
})

env.PORT // number — TypeScript knows this
Enter fullscreen mode Exit fullscreen mode

The schema is your single source of truth. Every env var, its type, its constraints — one declaration. The library generates proper error messages, handles type coercion, and gives you full TypeScript inference.

Handling Different Types

Env vars are always strings, but your app needs real types.

  • Numbers: Parse with Number() or use a schema that does it for you. Watch out for NaN — Number("abc") returns NaN, not an error.
  • Booleans: "true" / "false", "yes" / "no", "1" / "0" — decide what you accept. A library like CtroEnv handles all these variants.
  • Enums / Pick from a set: You want to restrict a value to "development" | "production". With schemas, you use pick(["dev", "prod"]). With raw code, you'd write a check against an array.

Working with .env Files

.env files are not a Node.js feature — they're a convention popularized by dotenv. The file looks like this:

PORT=4000
DATABASE_URL=postgres://localhost:5432/myapp
Enter fullscreen mode Exit fullscreen mode

In Node.js, you load them at the top of your entry file:

import "dotenv/config"
// or
import { loadEnv } from "@ctroenv/node"
await loadEnv()
Enter fullscreen mode Exit fullscreen mode

Important: .env files belong in .gitignore. They contain secrets. Your repo should have a .env.example that documents every variable without real values.

Secrets: What Not to Do

Never log env vars. Never pass them to error reporting services. Never commit them to git. Never forward them to third-party APIs as-is if they contain secrets.

If you're using CtroEnv, marking a variable as .secret() masks its value in console output and stringification:

const env = defineEnv({
  JWT_SECRET: string().secret(),
})

console.log(env.JWT_SECRET) // "********"
env.meta.get("JWT_SECRET")  // actual value
Enter fullscreen mode Exit fullscreen mode

This prevents accidental leaks during debugging or logging.

CI/CD: Validate Before Deploy

The worst time to discover a missing env var is at 3 AM after a deploy. Validate early:

# Using CtroEnv CLI
npx ctroenv validate --source .env.production

# Or just run a script that imports your config
node -e "require('./src/config').validate()"