envguard

A zero-boilerplate environment variable validator and analysis tool for Node.js.

🛡️ Validate: Coerce types and enforce schemas at startup.
🔍 Analyze: Detect unused or missing variables in your codebase.
📊 Dashboard: Visualize your environment health in a local dev UI.

---

Install

npm install @rohansm14/envguard

---

⚡ Quick Start

1. Validate & Coerce

Call it at app startup to ensure your environment is safe.

import 'dotenv/config'
import { guard } from '@rohansm14/envguard'

const env = guard({
  PORT:         { type: 'number',  default: 3000 },
  DATABASE_URL: { type: 'string',  required: true },
  JWT_SECRET:   { type: 'string',  required: true, minLength: 32 }
})

app.listen(env.PORT)

2. Infer Types (Zero-schema)

Don't want to maintain a schema? inferEnv() automatically detects types.

import { inferEnv } from '@rohansm14/envguard'
const env = inferEnv()

// "3000"  → 3000 (number)
// "true"  → true (boolean)

---

🔍 Codebase Analysis (CLI)

envguard scans your entire project to find discrepancies between your .env file and your code usage.

npx envguard

It identifies:

• Unused: Variables defined in .env but never used in code.
• Missing: process.env.VAR calls in code that aren't defined in .env.
• Invalid: Variables set to null, undefined, or empty strings.

---

📊 Dev Dashboard (UI)

Launch a local dashboard to visualize your environment health in real-time.

npx envguard dev-ui

Starts a server at http://localhost:3000 with:

• Real-time Polling: Updates automatically as you edit files.
• Type Mismatches: Flagged conflicts between your values and an optional env.schema.js.
• Status Badges: Clear ✓, ⚠, and ✗ indicators for every variable.

⚠️ Important: How to View the Dashboard

The dashboard is a web application that requires the envguard local server to be running.

• Do NOT open index.html directly from your browser (using File > Open or double-clicking).
• If you open the file directly, it will show empty stats because it won't be able to connect to the backend scanner.
• Always use the command: npx envguard dev-ui and navigate to http://localhost:3000.

Requirements

• Project Root: Run the command from your project's root directory.
• .env file: Must have a .env file present for comparison.
• Code Usage: Must have at least one process.env.VAR usage in your code for the scanner to detect.

---

What it does

• Deep Scanning: Detects dot notation (process.env.VAR), bracket notation (process.env['VAR']), and destructuring (const { VAR } = process.env).
• Robust Parsing: Correctly handles comments, quotes, and optional chaining (process.env?.VAR).
• One Combined Error: Logs all validation failures at once so you can fix them in one go.
• Zero Dependencies: Lightweight and fast, built on native Node.js logic.

---

Schema Options

Option	Type	Description
type	'string' 'number' 'boolean'	Expected type. Others are coerced.
required	boolean	Throws if the var is not set.
default	any	Fallback value if the var is not set.
minLength	number	Minimum character length for strings.

---

License

MIT