Two weeks ago I deployed a service that crashed on the first request. Not because the code was wrong — because process.env.DATABASE_URL was undefined and nobody caught it until a user hit the endpoint.
I've made this mistake enough times to recognize the pattern: environment variables in Node.js are string | undefined. TypeScript shrugs. Validation is your problem. Most teams don't do it, or they scatter it across 15 files with parseInt() and ?? operators.
The Three Lies process.env Tells You
1. "This variable exists"
const dbUrl = process.env.DATABASE_URL
// ^? string | undefined — TypeScript can't help
It might exist. It might not. You won't know until runtime. If it's undefined, the error surfaces at the point of first use — not at startup.
2. "This value is the right type"
const port = process.env.PORT // "3000" — it's a string!
app.listen(port + 1) // listens on "30001", not 3001
PORT is semantically a number. At runtime it's a string. Every consumer has to parse it. Nobody does it consistently.
3. "The format is correct"
// .env
DATABASE_URL=localhost:5432/myapp // forgot postgres://
// somewhere in your app
new URL(process.env.DATABASE_URL) // TypeError: Invalid URL
No error at import. No error at server start. The first database query crashes.
The Manual Approach
I've written this function more times than I can count:
function getEnv() {
const dbUrl = process.env.DATABASE_URL
if (!dbUrl) throw new Error("DATABASE_URL is required")
const port = parseInt(process.env.PORT ?? "3000", 10)
if (isNaN(port) || port < 1 || port > 65535) {
throw new Error("PORT must be between 1 and 65535")
}
const nodeEnv = process.env.NODE_ENV ?? "development"
if (!["development", "production", "test"].includes(nodeEnv)) {
throw new Error(`Invalid NODE_ENV: ${nodeEnv}`)
}
return { dbUrl, port, nodeEnv } as const
}
It works. But it's repetitive, undocumented, and TypeScript can't infer literal types from it. Every project reinvents this same function with slightly different bugs.
Schema-Based Validation
CtroEnv does the same thing with a schema:
import { defineEnv, string, number, pick } from "@ctroenv/core"
const env = defineEnv({
DATABASE_URL: string().url().describe("PostgreSQL connection URL"),
PORT: number().port().default(3000),
NODE_ENV: pick(["development", "production", "test"] as const).default("development"),
})
-
env.PORTisnumber— already parsed -
env.NODE_ENVis"development" | "production" | "test"— exact union, no typos -
env.DATABASE_URLisstring— guaranteed present and valid
If anything is missing or invalid, defineEnv() throws immediately with every error grouped:
● Missing required (1)
DATABASE_URL Add this variable to your .env file
✗ Invalid (1)
PORT Expected a port number (1-65535), received 0
No hunting through logs. The app crashes at import time, not on the first request.
What You Get
| Problem | Raw process.env | CtroEnv |
|---|---|---|
| Type safety | `string \ | undefined` |
| Startup validation | None | All vars validated |
| Error clarity | cannot read property of undefined |
Grouped, descriptive |
| Defaults | Manual ??
|
.default() |
| Secret handling | Silent |
.secret() masks at runtime |
| CI integration | None |
ctroenv check, ctroenv validate
|
The Validators
string().url() // valid URL
string().email() // valid email (HTML5 regex)
string().port() // port 1-65535
string().min(8) // minimum length
string().max(255) // maximum length
string().hostname() // RFC 1123 hostname
string().regex(/^[a-z]+$/) // custom pattern
number().int() // integer
number().positive() // > 0
number().port() // 1-65535
number().min(1) // minimum value
number().max(100) // maximum value
boolean() // "true"/"false", "yes"/"no", "1"/"0", "y"/"n"
pick(["dev", "prod"]) // exact string union
// Chainable on all validators:
.optional() .default(v) .describe(t) .secret() .validate(fn)
One line per variable, and TypeScript infers everything from the schema.
npm install @ctroenv/core