What each layer does
| Feature | dotenv | config library |
|---|---|---|
Read .env into the environment | yes | usually relies on dotenv or the platform |
| Required keys | no | yes |
Types ("3000" → 3000) | no | yes |
| Defaults | no | yes |
| Format checks (URL, enum, prefix) | no | yes |
| Fail fast at startup | no | yes |
| Typed access in the editor | no | yes (zod, t3-env, envalid) |
The main options
zod (plain schema)
import "dotenv/config";
import { z } from "zod";
export const env = z.object({
NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
PORT: z.coerce.number().default(3000),
DATABASE_URL: z.string().url(),
}).parse(process.env);t3-env (@t3-oss/env-nextjs, @t3-oss/env-core)
Zod-based, with separate server and client sections so a server secret can't be imported into client code by mistake. The common choice for Next.js; background in NEXT_PUBLIC_ variables.
envalid
import { cleanEnv, port, url, str } from "envalid";
export const env = cleanEnv(process.env, {
PORT: port({ default: 3000 }),
DATABASE_URL: url(),
NODE_ENV: str({ choices: ["development", "test", "production"] }),
});convict and node-config
convict (from Mozilla) defines a schema with formats and env-var mappings and suits deep config trees. node-config merges files from a config/ folder (default.json, production.json) and maps env vars through custom-environment-variables.json. Both are heavier and assume Node APIs, so they don't fit edge runtimes.
Decision matrix
| Situation | dotenv only | dotenv + config library |
|---|---|---|
| prototype, < 10 variables | fine | optional |
| TypeScript codebase | no types | recommended |
| more than ~15 variables | error-prone | recommended |
| dev / staging / prod | works | catches drift at startup |
| serverless / edge | works | zod or envalid (no Node-only deps) |
| onboarding new developers | .env.example | schema + .env.example |
Recommended setup
.env(git-ignored) holds the values locally; production sets real environment variables..env.examplelists every key, made with the .env.example generator.- A schema module (zod/t3-env/envalid) validates at startup and exports a typed
envobject; the rest of the code importsenv, neverprocess.env. - CI starts the app with
.env.examplevalues to prove that every required key is declared.
Before parsing, catch file-level problems (syntax, duplicates, unquoted #) with the .env validator; to find variables the code reads but the schema lacks, scan the code with the missing env detector.
Frequently asked questions
Does a config library replace dotenv?
Usually not. dotenv (or node --env-file) still loads the file in development; the library validates and types what was loaded. In production, the platform provides the variables and the same schema validates them.
Which library for plain JavaScript?
envalid: small, readable, and it returns a cleaned object with the right types. zod also works in JavaScript, you just don't get editor types.
Does validation slow down serverless cold starts?
Barely: it runs once when the module loads. The bigger issue is that convict and node-config rely on Node APIs that edge runtimes lack; zod and envalid don't.
What changes in production when I add validation?
A missing or invalid variable crashes the deploy at boot with a clear message, instead of surfacing later as undefined in a database call or a 500 for users.
Is a config library worth it for a tiny project?
Often not yet. A .env.example and a startup check for the two or three critical keys are enough until the variable list grows.