compareBy Aliniyaz Mamat · updated

dotenv vs config: which should you use in 2026?

dotenv vs a config library is not either/or: dotenv only loads a .env file into process.env; a config library (zod, t3-env, envalid, convict, node-config) validates, types and defaults those values. Small projects get by with dotenv alone; once you have many variables, several environments or TypeScript, add a config layer on top.

Key takeaways

  • ✓dotenv: parse the file, copy keys into process.env. No validation, no types, no defaults.
  • ✓A config library turns a missing or malformed variable into a crash at startup instead of a bug in production traffic.
  • ✓For TypeScript, a zod schema (or @t3-oss/env-nextjs / env-core) gives typed env.PORT: number with little code.
  • ✓For plain JavaScript, envalid is the lightest option; convict and node-config suit large, hierarchical configs.
  • ✓Keep .env as the source of values in development; the schema is the documentation of what exists.

What each layer does

Featuredotenvconfig library
Read .env into the environmentyesusually relies on dotenv or the platform
Required keysnoyes
Types ("3000" → 3000)noyes
Defaultsnoyes
Format checks (URL, enum, prefix)noyes
Fail fast at startupnoyes
Typed access in the editornoyes (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

Situationdotenv onlydotenv + config library
prototype, < 10 variablesfineoptional
TypeScript codebaseno typesrecommended
more than ~15 variableserror-pronerecommended
dev / staging / prodworkscatches drift at startup
serverless / edgeworkszod or envalid (no Node-only deps)
onboarding new developers.env.exampleschema + .env.example

Recommended setup

  1. .env (git-ignored) holds the values locally; production sets real environment variables.
  2. .env.example lists every key, made with the .env.example generator.
  3. A schema module (zod/t3-env/envalid) validates at startup and exports a typed env object; the rest of the code imports env, never process.env.
  4. CI starts the app with .env.example values 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.

Related tools

Continue reading