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

Why dotenv-diff?

• 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

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

Writing a good .env.example

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

Drift Warnings

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.

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.

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.

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