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.

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

---

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