I've built enough projects to know that environment variable validation isn't glamorous — until your app silently uses undefined as a database URL. There are a bunch of tools for this now, and picking the wrong one means either fighting your tool or fighting your own config. Here's how they stack up.
The candidates
| Tool | Size | Dependencies | CLI | Framework support |
|---|---|---|---|---|
| CtroEnv | under 5 KB gzip | 0 | Yes | Node, Vite, Next.js |
| Zod + manual | 50 KB+ | 0 (Zod itself is ~13 KB gzip, plus your glue) | No | You build it |
| envalid | 8 KB gzip | 6 (legacy deps) | No | Node only |
| t3-env | ~15 KB | Depends on Zod | No | Next.js only |
Let's look at each one.
Zod + manual parsing
Zod is great for runtime validation in general, and lots of people use it for env vars because they already have it in their project.
import { z } from "zod";
const schema = z.object({
DATABASE_URL: z.string().url(),
PORT: z.coerce.number().int().min(0).max(65535).default("3000"),
NODE_ENV: z.enum(["dev", "prod"]),
});
const parsed = schema.safeParse(process.env);
if (!parsed.success) {
console.error(parsed.error.format());
process.exit(1);
}
const env = parsed.data;
What it does well: If you're already using Zod, this is zero extra dependencies. Zod's type inference is excellent. The error formatting is detailed.
What it doesn't do: No CLI, no .env.example generation, no secret masking, no framework adapters. You write your own process.exit(1) boilerplate every time. Coercion for numbers/booleans is manual — z.coerce.number() doesn't reject non-numeric strings gracefully. No way to generate docs from your schema.
When to pick it: You already have Zod in your project, you only have 3-4 env vars, and you don't mind writing the glue code. For anything bigger, the boilerplate gets annoying fast.
envalid
envalid was the early leader here. It's been around since the days of dotenv and has a simple API.
import { cleanEnv, str, port, num, makeValidator } from "envalid";
const env = cleanEnv(process.env, {
DATABASE_URL: str(),
PORT: port({ default: 3000 }),
NODE_ENV: str({ choices: ["dev", "prod"] }),
});
What it does well: Dead simple. The makeValidator API for custom types is straightforward. Reports all errors at once instead of failing on the first one.
What it doesn't do: It's Node-only, so no Vite or Next.js integrations. The error messages are pretty basic — you get a string like "DATABASE_URL" is missing, but no grouped or colored output. The choices option is oddly attached to str() rather than being a proper pick type. It has 6 legacy dependencies (some unmaintained). No CLI, no env file generation, no ENVIRONMENT.md generation. Secret masking isn't built in.
When to pick it: You need something simple for a Node backend and don't want to learn a new API. It works, but you'll outgrow it quickly if your project grows.
t3-env
Created by the t3-stack team, this one wraps Zod with nice DX and is tightly coupled to Next.js.
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";
export const env = createEnv({
server: {
DATABASE_URL: z.string().url(),
},
client: {
NEXT_PUBLIC_API_URL: z.string().url(),
},
runtimeEnv: process.env,
});
What it does well: The server/client split is genius for Next.js. It prevents accidentally leaking server-only vars to the client bundle. Great integration with Next.js build process.
What it doesn't do: It's Next-only. If you extract it for other frameworks, you're fighting it. It depends on Zod (15 KB+ added). No CLI, no .env.example generation, no docs generation. The runtimeEnv option is annoying — you have to manually pass process.env in development and inline values in production. Secret masking isn't built in.
When to pick it: You're all-in on the Next.js / t3-stack ecosystem. If you ever leave Next, you'll need to replace it.
CtroEnv
Full disclosure: I built this one. I wanted something that worked everywhere without dragging in a schema library I didn't need.
import { defineEnv, string, number, pick } from "@ctroenv/core";
const env = defineEnv({
DATABASE_URL: string().url(),
PORT: number().port().default(3000),
NODE_ENV: pick(["dev", "prod"] as const),
});
env.DATABASE_URL; // typed as string
Zero dependencies. under 5 KB gzipped. Validators are chainable and self-contained — no Zod dependency.
// Secret masking is built in
const env = defineEnv({
JWT_SECRET: string().min(32).secret(),
});
console.log(env.JWT_SECRET); // "********"
env.meta.get("JWT_SECRET"); // actual value
# CLI is included
npx @ctroenv/cli validate # validate current env
npx @ctroenv/cli generate # create .env.example from schema
npx @ctroenv/cli docs # generate ENVIRONMENT.md
npx @ctroenv/cli check # CI-friendly diff
// Framework adapters
// @ctroenv/node — reads process.env + .env files
// @ctroenv/vite — reads import.meta.env, build plugin
// @ctroenv/nextjs — server/client split like t3-env
What it does well: Framework-agnostic core, but has adapters when you need them. CLI for everyday tasks. Generates .env.example and docs from schema so they can't drift. Secret masking is built into the runtime, not bolted on. Error grouping and colored output for CI.
What it doesn't do: It's newer, so smaller ecosystem. No Zod compatibility layer (and that's by design — the APIs are different). The custom validator API uses a different pattern than Zod's.
When to pick it: You want zero-dependency validation that works across frameworks. You hate maintaining .env.example by hand. You want one tool for dev, CI, and docs.
Which one should you use?
If you're on Next.js and already have Zod, t3-env is fine. If you just need 3 vars validated, envalid works. If you love Zod and want to own your parsing pipeline, go for it.
If you want something that handles the whole lifecycle — validation, docs generation, CI checks, secret masking — CtroEnv does that without pulling in a 50 KB schema library. But it's also the newest option, so weigh that.
Pick based on your project, not hype. Each of these tools solves the same problem differently, and none of them are wrong.
Top comments (0)