Unlike other env validators that force you to write schemas manually, dotenv-audit scans your actual code to find every process.env usage - then validates them all.

The Problem

> App crashes in production
> "Cannot read property of undefined"
> Turns out someone forgot to set DATABASE_URL
> 3 hours of debugging...

dotenv-audit prevents this. One command. It finds every env variable your code uses and tells you exactly what's missing.

Install

npm install dotenv-audit

Quick Start

# Just run it - no config needed
npx dotenv-audit

That's it. dotenv-audit will:

1. Scan all your project files (.js, .ts, .jsx, .tsx, .vue, .svelte)
2. Find every process.env.XXXX usage automatically
3. Check which variables are actually set
4. Show a clear report of what's missing

Output

  dotenv-audit  v1.0.0
  ──────────────────────────────────────────
  Scanned 47 files · Found 12 env variables

  x MISSING (2)

    x DATABASE_URL
      > src/db/connect.ts:14

    x JWT_SECRET
      > src/auth/middleware.js:7

  ! 3 warning(s) - use --verbose to see details

  / SET (10)

  ──────────────────────────────────────────
  2 missing · 10 set

Interactive Mode

npx dotenv-audit --ask

Asks you step by step:

? Generate ENV_SETUP.md file with all missing variables? (yes/no): yes
  Created ENV_SETUP.md with 12 variables

? Create new .env file with missing variables? (yes/no): yes
  Created .env with 12 variables

Generated .env has smart placeholder values based on variable names:

# -- Database ────────────────────────────────
DATABASE_URL=mongodb://localhost:27017/your_database_name
REDIS_CONNECTION_STRING=redis://localhost:6379

# -- Authentication ──────────────────────────
JWT_SECRET=your_jwt_secret_key_min_32_chars_long

# -- AI / LLM ────────────────────────────────
OPENAI_API_KEY=sk-your_openai_api_key_here
ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here

# -- AWS ─────────────────────────────────────
AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_REGION=us-east-1

It even auto-detects your database from package.json - if you use mongoose, it gives mongodb:// URLs, not postgresql://.

Monorepo Support

dotenv-audit auto-detects monorepos (pnpm workspaces, lerna, turbo) and creates separate .env files per service:

? Create/update .env inside each service folder? (yes/no): yes

  api/.env                    — created with 25 variables
  client/.env                 — created with 14 variables
  services/payments/.env      — created with 7 variables

  Done! 3 service .env files processed

Detection Patterns

// All of these are detected:

process.env.DATABASE_URL              // dot access
process.env["API_KEY"]                // bracket access
process.env['SECRET']                 // single quotes
const { PORT, HOST } = process.env    // destructuring
process.env.PORT || 3000              // with defaults (warning, not error)
process.env.DEBUG ?? false            // nullish coalescing
import.meta.env.VITE_API_URL         // Vite env

// Smart filtering:
import.meta.env.DEV                   // SKIPPED (Vite built-in)
import.meta.env.MODE                  // SKIPPED (Vite built-in)
// process.env.COMMENTED               // SKIPPED (in comments)
process.env[dynamicVar]               // warned (can't validate)

CLI Commands

# Scan current directory
npx dotenv-audit

# Scan specific directory
npx dotenv-audit ./src

# Interactive mode - generates .env and ENV_SETUP.md
npx dotenv-audit --ask

# Verbose output (show warnings + all set vars)
npx dotenv-audit --verbose

# Strict mode (empty strings = error)
npx dotenv-audit --strict

# JSON output (great for CI)
npx dotenv-audit --json

# CI mode (exit code 1 if vars missing)
npx dotenv-audit --ci

# List all detected vars
npx dotenv-audit audit

# Auto-generate .env.example
npx dotenv-audit gen

# Create config file
npx dotenv-audit init

Programmatic API

// At app startup - validate and throw on missing
require('dotenv-audit').protect()

// Same but never throws - returns results
const result = require('dotenv-audit').check()
console.log(result.ok)       // true/false
console.log(result.missing)  // ['DB_URL', 'SECRET']
console.log(result.set)      // ['PORT', 'NODE_ENV']

// Detailed audit
const audit = require('dotenv-audit').audit()
// audit.variables = [{ name, locations, hasDefault, value }]

// Generate .env.example content
const content = require('dotenv-audit').genExample()

protect() Options

require('dotenv-audit').protect({
  rootDir: __dirname,
  strict: true,            // treat empty strings as errors
  required: ['DB_URL'],    // always require these
  optional: ['DEBUG'],     // never error on these
  ignoreVars: ['TEST'],    // completely ignore
  exitOnError: true,       // throw on missing (default: true)
  format: 'pretty',        // 'pretty' | 'json' | 'silent'
  verbose: false
})

Configuration

Option 1: package.json

{
  "dotenv-audit": {
    "strict": false,
    "required": ["DATABASE_URL", "JWT_SECRET"],
    "optional": ["DEBUG", "LOG_LEVEL"],
    "ignoreVars": ["npm_package_version"],
    "ignore": ["scripts/"]
  }
}

Option 2: .dotenv-auditrc

{
  "strict": false,
  "required": ["DATABASE_URL"],
  "optional": ["DEBUG"],
  "ignoreVars": [],
  "ignore": []
}

Option 3: dotenv-audit.config.js

module.exports = {
  strict: process.env.NODE_ENV === 'production',
  required: ['DATABASE_URL', 'JWT_SECRET'],
  optional: ['DEBUG']
}

Framework Support

Auto-detects your framework and understands framework-specific patterns:

| Framework | Prefix | Auto-detected | |-----------|--------|:---:| | Next.js | NEXT_PUBLIC_* | Yes | | Vite | VITE_* | Yes | | Nuxt | NUXT_* | Yes | | Gatsby | GATSBY_* | Yes | | SvelteKit | PUBLIC_* | Yes | | Astro | PUBLIC_* | Yes | | Express/Fastify/NestJS | - | Yes |

Database Auto-Detection

dotenv-audit reads your package.json to give correct placeholder values:

| Dependency | DATABASE_URL placeholder | |---|---| | mongoose / mongodb | mongodb://localhost:27017/your_database_name | | pg / postgres | postgresql://user:password@localhost:5432/your_database_name | | mysql / mysql2 | mysql://user:password@localhost:3306/your_database_name | | prisma | Reads schema.prisma to detect actual DB |

Use in CI/CD

# GitHub Actions
- name: Validate env vars
  run: npx dotenv-audit --ci --json
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    JWT_SECRET: ${{ secrets.JWT_SECRET }}

Best Practice

// app.js
require('dotenv').config()     // 1. load vars
require('dotenv-audit').protect()   // 2. validate vars
// ... rest of your app

Comparison

| Feature | dotenv | envalid | env-var | dotenv-audit | |---------|--------|---------|---------|-------------| | Load .env | Yes | Yes | No | No* | | Validate | No | Yes | Yes | Yes | | Auto-detect from code | No | No | No | Yes | | Zero schema needed | - | No | No | Yes | | .env.example cross-check | No | No | No | Yes | | Generate .env file | No | No | No | Yes | | Generate ENV_SETUP.md | No | No | No | Yes | | Framework detection | No | No | No | Yes | | Database auto-detect | No | No | No | Yes | | Monorepo support | No | No | No | Yes | | Interactive mode | No | No | No | Yes | | CLI tool | No | No | No | Yes | | Zero dependencies | Yes | No | No | Yes |

* dotenv-audit validates, not loads. Use alongside dotenv for loading.

License

MIT