dotenv-diff

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 and Next.js. Also works well in modern JavaScript/TypeScript projects and frameworks like Node.js, Nuxt, and Vue — or any other setup where you want reliable .env file comparison.

Warnings & errors detection

Clean / successful scan

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 and Next.js 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.

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