dotenv-diff

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

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

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

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.

An .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

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.

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.

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:

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

• 0 → No errors
• 1 → 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