env-validation

A strict, lightweight, zero-runtime-dependency environment variable validator for Node.js, supporting both JavaScript and TypeScript.

env-validation helps you fail fast at application startup by validating, parsing, and normalizing environment variables in a clean, predictable, and production-safe way.

📘 Description

In most Node.js applications, environment variables are accessed directly through process.env.This is flexible, but dangerous:

• All values are strings
• Missing variables fail silently
• Invalid values cause runtime bugs
• Configuration errors appear too late (in production)

env-validation solves this problem by validating your environment configuration once, at startup.

If any variable is missing, invalid, or misconfigured, the application throws immediately and exits, preventing broken deployments and undefined behavior.

✨ Features

• ✅ Works with JavaScript & TypeScript
• ✅ Zero runtime dependencies
• ✅ Strong runtime validation
• ✅ Type casting (string, number, boolean)
• ✅ Required variable enforcement
• ✅ Default values
• ✅ Enum validation
• ✅ Detect unused environment variables
• ✅ Optional auto-injection into process.env
• ✅ CI & production safe (fail-fast)

✅ Best Practices

• Call validateEnv() only once
• Call it before any application logic
• Enable strictUnused in production
• Keep all environment validation in one place

📦 Node Compatibility

• Node.js >= 16
• Works with CommonJS & ESM

📦 Installation

npm install validation-env dotenv

Create a .env file (example)

• PORT=3000
• NODE_ENV=dev
• DB_HOST=localhost
• DB_PORT=3306
• DEBUG=true

🔧 Usage Examples

Add env-validation once at your application entry file (e.g. index.js, index.ts, app.js, server.js, main.ts).

✅ JavaScript Example

index.js

require("dotenv").config();
const { validateEnv } = require("env-validation");

const { env } = validateEnv(
  {
    PORT: "number|required",
    NODE_ENV: "enum:dev,prod,staging|required",
    DB_HOST: "string|required",
    DB_PORT: "number|default:3306",
    DEBUG: "boolean|default:false"
  },
  {
    inject: true,
    strictUnused: process.env.NODE_ENV === "production"
  }
);

// Use validated values safely
console.log("Server running on port:", env.PORT);

🟦 TypeScript Example

This example shows how to use env-validation in a TypeScript Node.js application.

Add this code once at application startup, typically in:

• index.ts
• main.ts
• server.ts
• app.ts

✅ TypeScript Example

index.ts

import "dotenv/config";
import { validateEnv } from "env-validation";

const { env } = validateEnv(
  {
    PORT: "number|required",
    NODE_ENV: "enum:dev,prod,staging|required",
    DB_HOST: "string|required",
    DB_PORT: "number|default:3306",
    DEBUG: "boolean|default:false"
  },
  {
    inject: true,
    strictUnused: process.env.NODE_ENV === "production"
  }
);

// ✅ Fully validated & parsed values
env.PORT;      // number
env.DB_PORT;  // number
env.DEBUG;    // boolean
env.NODE_ENV; // string

📜 License

MIT © Sagar Pipaliya