chrilleweb/dotenv-diffValidate environment variable usage in codebase
Scan your codebase to detect every environment variable reference. It helps you catch missing, unused, duplicated, and misused variables early, before they cause runtime errors.
First class support for SvelteKit, Next.js, and Nuxt. Also works well in modern JavaScript/TypeScript projects and frameworks like Node.js and Vue — or any other setup where you want reliable .env file comparison.
✨ Featured in awesome-cli-apps - A curated list of awesome CLI applications
→ See Capabilities Documentation for details on what the scanner checks for and how it works.
--init)Generate a default configuration file:
dotenv-diff --init
→ See Configuration Documentation for more details.
Easily integrate dotenv-diff into your Git hooks or CI/CD pipelines to enforce environment variable consistency.
→ See Git Hooks Documentation for more details.
In SvelteKit, Next.js, and Nuxt projects, dotenv-diff detects framework specific environment variable misuse.
▸ Framework issues (SvelteKit)
──────────────────────────────────────────────────────────────────────
PUBLIC_API_URL $env/dynamic/private
variables must not start
with "PUBLIC_"
src/routes/+page.server.ts:3
──────────────────────────────────────────────────────────────────────
→ See Framework Documentation for more details.
.env.exampleAn .env.example written so it's easier to understand for new contributors to the team:
# Node environment (development, production, etc.)
# @optional
NODE_ENV=development
# Public API URL is used to call our backend
PUBLIC_API_URL=http://localhost:3000
# Temporary token for the partner API sandbox — ask the integrations team for a new one
# @expire 2027-03-31
PARTNER_API_TOKEN=
→ Read more: Writing a Good .env.example
A scan compares your code against a single file — so any key you add to .env and forget in .env.example is invisible until a new contributor clones the repo. Drift warnings catch exactly that:
▸ Drift between .env and .env.example
──────────────────────────────────────────────────────────────────────
STRIPE_SECRET not documented in .env.example
──────────────────────────────────────────────────────────────────────
On by default; opt out with --no-drift-warnings.
→ See Drift Warnings for more details.
Add expiration metadata to your environment variables to get warnings when they are about to expire. For example, in your .env file:
# @expire 2025-12-31
API_TOKEN=
→ See Expiration Documentation for more details.
You can ignore specific environment variable warnings by adding comments in your code. For example:
const apiKey = process.env.API_KEY; // dotenv-diff-ignore
This is helpful when you know a specific warning is safe in your source code.
→ See Ignore Comments Documentation for more details.
--baseline)Adopt dotenv-diff in projects that already have known warnings by recording the current state into a baseline file. Future runs will only report newly introduced issues:
dotenv-diff --baseline
→ See Baseline Documentation for more details.
--explain)Inspect a specific environment variable to see where it is defined, where it is used in the codebase, and its overall status:
dotenv-diff --explain DATABASE_URL
→ See --explain Documentation for more details.
In monorepos with multiple apps and packages, you can include shared folders:
{
"scripts": {
"dotenv-diff": "dotenv-diff --example .env.example --include-files '../../packages/**/*' --ignore VITE_MODE"
}
}
→ See Monorepo Documentation for more details.
This will:
0 → No errors1 → Errors found (or warnings in strict mode)→ See dotenv-diff Documentation for full documentation
Issues and pull requests are welcome.
→ See CONTRIBUTING for details.
Thanks to these amazing people for contributing to this project:
Licensed under the MIT license.
Created by chrilleweb