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

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

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"

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"),
}

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

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

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

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

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

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()"

Run this in your CI pipeline after install, before build. If validation fails, fail the build.

Framework Specifics

Node.js (Express, Fastify, etc.): Use process.env directly, or better, load your config module at startup. CtroEnv's Node adapter adds .env file loading on top.

Vite: process.env doesn't exist in the browser. Vite exposes import.meta.env for public variables. Use VITE_ prefix for client-side vars. The CtroEnv Vite plugin bridges this.

Next.js: Next.js inlines process.env at build time for any var referenced in server code. But NEXT_PUBLIC_ vars get inlined into client bundles. Use CtroEnv's Next.js adapter for proper server/client split handling.

Wrapping Up

You don't need a library to read env vars. But you do need some system to validate them, type them, and catch missing values before runtime. Whether that's a 10-line function or a schema library is up to you and the size of your project.

The important thing is: don't access process.env directly across 40 files. Centralize. Validate. Let TypeScript know what's going on.

Links: GitHub | npm | Docs

推荐订阅源

DEV Community