https://github.com/Chrilleweb/dotenv-diff
Validate environment variable usage in codebase
https://github.com/Chrilleweb/dotenv-diff
cli developer-tools dotenv-cli environment-variables open-source security typescript
Last synced: 5 days ago
JSON representation
Validate environment variable usage in codebase
- Host: GitHub
- URL: https://github.com/Chrilleweb/dotenv-diff
- Owner: Chrilleweb
- License: mit
- Created: 2025-07-10T19:41:13.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-05-21T14:37:15.000Z (11 days ago)
- Last Synced: 2026-05-21T23:41:27.055Z (11 days ago)
- Topics: cli, developer-tools, dotenv-cli, environment-variables, open-source, security, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/dotenv-diff
- Size: 4.72 MB
- Stars: 49
- Watchers: 1
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-cli-apps - dotenv-diff - Validate environment variable usage in a codebase. (Development / Chat)
- fucking-awesome-cli-apps - dotenv-diff - Validate environment variable usage in a codebase. (Development / Chat)
README
# 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.
[](https://codecov.io/gh/Chrilleweb/dotenv-diff)
[](https://www.npmjs.com/package/dotenv-diff)
[](https://www.npmjs.com/package/dotenv-diff)
> **✨ Featured in [awesome-cli-apps](https://github.com/agarrharr/awesome-cli-apps#development)** - A curated list of awesome CLI applications
---
### 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](./docs/capabilities.md) for details on what the scanner checks for and how it works.
---
## Configuration (`--init`)
Generate a default configuration file:
```bash
dotenv-diff --init
```
→ See [Configuration Documentation](./docs/configuration_and_flags.md#configuration-file) 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](./docs/git_hooks_ci.md) for more details.
## Framework-Specific Warnings
In SvelteKit and Next.js projects, dotenv-diff detects framework-specific
environment variable misuses.
Example warning:
```bash
Framework issues (Sveltekit):
- PUBLIC_API_URL (src/routes/+page.ts:1)
→ $env/dynamic/private variables must not start with "PUBLIC_"
```
→ See [Framework Documentation](./docs/frameworks/index.md) for more details.
## Ignore Comments
You can ignore specific environment variable warnings by adding comments in your code. For example:
```javascript
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](./docs/ignore_comments.md) 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:
```bash
# @expire 2025-12-31
API_TOKEN=
```
→ See [Expiration Documentation](./docs/expiration_warnings.md) 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:
```bash
dotenv-diff --explain DATABASE_URL
```
→ See [--explain Documentation](./docs/configuration_and_flags.md#--explain-key) for more details.
---
## Monorepo support
In monorepos with multiple apps and packages, you can include shared folders:
```json
{
"scripts": {
"dotenv-diff": "dotenv-diff --example .env.example --include-files '../../packages/**/*' --ignore VITE_MODE"
}
}
```
→ See [Monorepo Documentation](./docs/monorepo_support.md) 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](./docs/index.md) for full documentation
---
## Contributing
Issues and pull requests are welcome.
→ See [CONTRIBUTING](./CONTRIBUTING.md) for details.
Thanks to these amazing people for contributing to this project:
---
## License
Licensed under the [MIT](LICENSE) license.
Created by [chrilleweb](https://github.com/chrilleweb)