GitHub - Chrilleweb/dotenv-diff: Validate 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

Why dotenv-diff?

Ensure all required environment variables are defined before deploying Catch missing or misconfigured variables early in development Improve collaboration by keeping teams aligned on required variables Reduce the risk of committing sensitive data Scale easily for monorepos and multi-environment setups

How It Works → See Capabilities Documentation for details on what the scanner checks for and how it works.

Configuration (--init) Generate a default configuration file: dotenv-diff --init → See Configuration Documentation for more details.

Git hooks and CI/CD Integration Easily integrate dotenv-diff into your Git hooks or CI/CD pipelines to enforce environment variable consistency. → See Git Hooks Documentation for more details. Framework-Specific Warnings In SvelteKit, Next.js, and Nuxt projects, dotenv-diff detects framework-specific environment variable misuses. Example warning: Framework issues (Sveltekit): - PUBLIC_API_URL (src/routes/+page.ts:1) → $env/dynamic/private variables must not start with "PUBLIC_" → See Framework Documentation for more details. Ignore Comments 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.

Expiration Warnings 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.

Suppress existing warnings (--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 a variable (--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.

Monorepo support 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:

Scan the current app Include shared packages Ignore variables used only in specific environments

Exit Codes

0 → No errors 1 → Errors found (or warnings in strict mode)

Documentation → See dotenv-diff Documentation for full documentation

Contributing Issues and pull requests are welcome. → See CONTRIBUTING for details. Thanks to these amazing people for contributing to this project:

License Licensed under the MIT license. Created by chrilleweb