dotenv-safe vs envscan

dotenv-safe ensures .env matches .env.example. envscan generates .env.example from your source code — so it can't go out of sync.

Jump to waitlist ↓

Side-by-side comparison

Feature dotenv-safe envscan
Validates .env at startup ✓ ✓
Auto-discovers vars from source ✗ ✓
Generates .env.example automatically ✗ ✓
Fails if .env.example is missing ✓ ✓
File + line location of each var ✗ ✓
Type inference (_PORT, _SECRET, _URL) ✗ ✓
Works as CI gate (exit code 1) ✓ ✓
GitHub Action with PR comments ✗ ✓ (CI tier)
Zero config — no schema file needed ✗ ✓

The workflow

dotenv-safe

# Install
npm install dotenv-safe

# You manually maintain .env.example:
# DATABASE_URL=
# PORT=
# JWT_SECRET=

# In your app entry point:
require('dotenv-safe').config();
// Throws if any key from .env.example
// is missing from .env

You maintain the list. Add process.env.NEW_KEY to your code, forget .env.example — dotenv-safe won't catch it until someone has an incomplete .env.

envscan

# Scan source code for env vars
$ envscan scan
Found 8 environment variables:
  DATABASE_URL    type: url     src/db.ts:12
  PORT            type: number  src/server.ts:5
  JWT_SECRET      type: secret  src/auth.ts:8

# Generate .env.example from what it finds
$ envscan generate
# Wrote .env.example (8 vars)

# Validate in CI
$ envscan validate
Validation: 7/8 vars set. Missing: JWT_SECRET
Exit code: 1

The schema is your codebase. envscan reads your source files — no manual list to maintain.

The stale .env.example problem

dotenv-safe enforces that .env matches .env.example — and that works well, provided .env.example is up to date. The problem: .env.example goes stale. You add process.env.NEW_API_KEY on Tuesday. You forget to update .env.example. dotenv-safe has no way to know. Three weeks later, someone's deploy fails.

envscan takes the opposite approach: scan source files to discover which vars you use. The schema comes from your code, not from a file you maintain manually.

When to use dotenv-safe

  • You need runtime validation that fires immediately at Node.js startup
  • Your .env.example is already well-maintained
  • Drop-in replacement for dotenv with one extra safety check
  • You don't need CI enforcement beyond startup

When to use envscan

  • You want .env.example generated, not written manually
  • You want CI to fail when a developer adds env vars without documenting them
  • You want file and line context for every discovered var
  • You want type hints (_PORT → number, _SECRET → redacted, _URL → url)

Get Early Access

envscan is in development. Join the waitlist to get notified at launch.

From the team behind textlens — 96/week npm downloads.

Get Early Access

$0 — no credit card required

Also comparing: envalid vs envscan →