"enum": ["development", "production", "test"],
"default": "development"
},
"API_KEY": {
"type": "string",
"required": true
}
}
}
Enter fullscreen mode Exit fullscreen mode
This schema declares:
- **PORT** must be a number, must be a valid port (1–65535), and defaults to 3000
- **DATABASE\_URL** must be a string, must be a valid URL, and is required
- **NODE\_ENV** can only be one of three values and defaults to `development`
- **API\_KEY** must be a string and is required
## [](#validating-your-env-file)Validating Your .env File
The tool we'll use is [env-haven](https://github.com/amitwaks/env-haven), a zero-dependency CLI that validates `.env` files against a JSON schema. Install it with a single command:
npx env-haven
Enter fullscreen mode Exit fullscreen mode
Save the schema above as `checkmyenv.config.json` in your project root. Then run:
env-haven
Enter fullscreen mode Exit fullscreen mode
If all variables are valid, you'll see:
env-haven — Environment Variable Validation
✓ PORT = 3000
✓ DATABASE_URL = postgresql://localhost:5432/myapp
✓ NODE_ENV = development
✓ API_KEY = sk-abc123
PASS 4 vars — 4 passed, 0 failed
Enter fullscreen mode Exit fullscreen mode
If something is wrong, you get clear error messages:
env-haven — Environment Variable Validation
✗ PORT = abc
│ "PORT" must be a number (got "abc")
│ "PORT" must be a valid port (1-65535, got "abc")
✗ NODE_ENV = staging
│ "NODE_ENV" must be one of: development, production, test (got "staging")
✗ API_KEY = (not set)
│ Missing required variable "API_KEY"
FAIL 4 vars — 1 passed, 3 failed
Enter fullscreen mode Exit fullscreen mode
The exit code is 1 on failure, which means you can plug this into any CI pipeline:
.github/workflows/validate-env.yml
name: Validate environment config
on: [pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npx env-haven
Enter fullscreen mode Exit fullscreen mode
This checks the default `.env` file. For staging or production, you can validate against different `.env` files by copying them into place before running the check.
## [](#going-further-generators)Going Further: Generators
Typing out your schema is useful, but env-haven can do more.
### [](#generate-a-envexample)Generate a .env.example
Keep your `.env.example` in sync with your schema automatically:
env-haven generate
Enter fullscreen mode Exit fullscreen mode
This produces:
env-haven: Generated .env.example
Enter fullscreen mode Exit fullscreen mode
The output file has every variable listed with its default value and a comment explaining what it's for. Required variables are marked explicitly:
Server port
PORT=3000
^^^ REQUIRED: uncomment and set this value
PostgreSQL connection string
DATABASE_URL=
Environment name
NODE_ENV=development
API authentication key
API_KEY=
Enter fullscreen mode Exit fullscreen mode
Required variables are uncommented so they fail loudly if unset. Optional ones are commented out with their defaults filled in. This makes onboarding new team members trivial — they can copy `.env.example` to `.env`, uncomment the variables they need, and go.
### [](#generate-typescript-types)Generate TypeScript Types
If you access environment variables through `process.env`, you've probably written something like this:
const port = parseInt(process.env.PORT || "3000", 10);
Enter fullscreen mode Exit fullscreen mode
This works, but it's verbose, error-prone, and doesn't scale. A better approach is to define a typed interface for your environment. env-haven can generate it for you:
env-haven types
Enter fullscreen mode Exit fullscreen mode
This creates an `env.d.ts` file:
// Auto-generated by env-haven
export interface Env {
readonly PORT: number;
readonly DATABASE_URL: string;
readonly NODE_ENV: string;
readonly API_KEY: string;
}
Enter fullscreen mode Exit fullscreen mode
Now you can use it in your application:
import type { Env } from "./env";
function getEnv(): Env {
return {
PORT: parseInt(process.env.PORT!, 10),
DATABASE_URL: process.env.DATABASE_URL!,
NODE_ENV: process.env.NODE_ENV!,
API_KEY: process.env.API_KEY!,
};
}
Enter fullscreen mode Exit fullscreen mode
Pair this with a validation step in your build, and you get compile-time confidence that your environment is correctly configured.
## [](#schema-reference)Schema Reference
Here's every validation rule available:
Rule
Example
What it checks
`type`
`"number"`, `"boolean"`, `"integer"`
Value has the correct JavaScript type
`required`
`true` / `false`
Value is present (unless a default is set)
`default`
`3000`
Fallback value when the variable is not set
`format`
`"url"`, `"email"`, `"port"`
Value matches an expected format
`enum`
`["dev", "prod"]`
Value is in the allow-list
`pattern`
`"^sk-"`
Value matches a regular expression
`min`
`1`
Minimum length (strings) or value (numbers)
`max`
`65535`
Maximum length (strings) or value (numbers)
Supported formats include: `url`, `email`, `port`, `uuid`, `hostname`, `path`, and `regexp`.
## [](#integrating-with-your-workflow)Integrating With Your Workflow
The most effective setup is three steps:
1. **Commit your schema** — `checkmyenv.config.json` lives in version control alongside your code
2. **Validate in CI** — run `npx env-haven` as a lint step in every pull request
3. **Generate on change** — run `env-haven generate` whenever the schema changes, and commit the updated `.env.example`
This creates a virtuous cycle: the schema is the source of truth, the `.env.example` is always accurate, and bad configuration never reaches production.
## [](#conclusion)Conclusion
Environment variable validation is one of those small investments that pays for itself the first time it catches a bug. A schema takes five minutes to write, but it prevents the kind of production incidents that take hours to debug.
The tool we used, [env-haven](https://github.com/amitwaks/env-haven), is open source (MIT), has zero dependencies, and runs in under 100ms. Try it on your next project:
npx env-haven
Enter fullscreen mode Exit fullscreen mode
Your future self — and your on-call rotation — will thank you.
