dotenv-guard

Validate env vars. Sync .env files. Prevent secret leaks.

Zero dependencies. Works with any Node.js project.

Install

npm install dotenv-guard

Quick Start

Add one line to your app entry:

import 'dotenv-guard/auto'; // App won't start if .env is missing required variables

Or use the CLI:

npx dotenv-guard sync          # .env vs .env.example
npx dotenv-guard validate      # Check types
npx dotenv-guard leak-check    # Find leaked secrets
npx dotenv-guard init          # Create .env.example + .gitignore
npx dotenv-guard install-hook  # Pre-commit hook

Type Hints

Add type hints in .env.example comments:

DATABASE_URL=postgresql://... # type:url
PORT=3000 # type:port
DEBUG=false # type:boolean
NODE_ENV=development # enum:development,staging,production
REDIS_URL= # type:url optional

Programmatic API

import { guard, syncCheck, validate, checkLeaks } from 'dotenv-guard';

// Quick guard — exits if missing vars
guard();

// Detailed sync check
const sync = syncCheck();
console.log(sync.missing); // ['API_KEY', 'SECRET']

// Custom validation
const errors = validate(process.env, [
  { key: 'PORT', type: 'port', required: true },
  { key: 'NODE_ENV', type: 'enum', enum: ['dev', 'staging', 'prod'] },
]);

// Leak detection
const leaks = checkLeaks();
if (leaks.leaks.length > 0) console.warn('Secrets leaked!');

Why?

• Missing env vars crash your app at runtime -> dotenv-guard catches them at startup
• Type mismatches (port as string, URL without protocol) -> dotenv-guard validates
• .env committed to git -> dotenv-guard blocks it with pre-commit hook
• Zero dependencies -> no supply chain risk, tiny bundle

License

MIT - Scuton Technology