dotenv-diff

Scan your entire 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

---

Automatic Fixes (--fix)

Automatically add missing variables to your .env file:

dotenv-diff --fix

Example

1. Code uses process.env.NEW_API_KEY
2. Run dotenv-diff --fix
3. Tool adds NEW_API_KEY= to .env or .env.example

---

Strict Mode

Treat warnings as errors (useful for CI):

dotenv-diff --strict

---

Framework-Specific Warnings

In SvelteKit and Next.js projects, dotenv-diff detects framework-specific environment variable misuses.

Example warning:

Framework issues (Sveltekit):
  - PUBLIC_URL (src/routes/+page.ts:1)
    → Variables accessed through import.meta.env must start with "VITE_"

---

Expiration Warnings

Add expiration metadata to variables:

# @expire 2025-12-31
API_TOKEN=

---

File Scanning Options

Include or exclude files:

dotenv-diff --include-files '**/*.js,**/*.ts' --exclude-files '**/*.spec.ts'

Override defaults:

dotenv-diff --files '**/*.js'

---

Compare Environment Files

dotenv-diff --compare

Compare specific files:

dotenv-diff --compare --env .env.local --example .env.example.local

---

Monorepo (Turborepo) Usage

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"
  }
}

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

Full documentation: https://dotenv-diff-docs.vercel.app

---

🤝 Contributing

Issues and pull requests are welcome.
For large changes, please open an issue first.

---

License

Licensed under the MIT license.

Created by chrilleweb