smart-env

⚡ Zero-dependency environment variable loader & validator for Node.js Fail fast. Ship safer. Keep it simple.

📌 Overview

smart-env is a lightweight Node.js utility that helps you load, validate, and enforce environment variables in your application.

It is designed to prevent common production issues caused by missing or misconfigured environment variables — without adding heavy dependencies.

🎯 Problem It Solves

Many Node.js applications:

• Load environment variables
• Forget to validate them
• Crash unexpectedly in production

smart-env ensures your app fails early with clear errors, making deployments safer and debugging easier.

✨ Features

• ✅ Zero external dependencies
• ✅ Fail-fast validation for required variables
• ✅ Supports default values
• ✅ Lightweight (~1–2 KB)
• ✅ Production-friendly
• ✅ Simple and readable API

🔍 Comparison

smart-env vs dotenv

| Feature | smart-env | dotenv | | ---------------------- | --------- | --------- | | External dependencies | ❌ None | ✅ Yes | | Environment validation | ✅ Yes | ❌ No | | Fail-fast behavior | ✅ Yes | ❌ No | | Default values support | ✅ Yes | ❌ No | | Minimal footprint | ✅ Yes | ⚠️ Medium |

📦 Installation

npm install @hamzas07/smart-env

🚀 Quick Start

import { loadEnv } from "@hamzas07/smart-env";

loadEnv({
  required: ["PORT", "DB_URL"],
  defaults: {
    PORT: 3000
  }
});

🖥️ Output Behavior

✅ When all variables are present

✅ Environment variables loaded

❌ When required variables are missing

❌ Missing environment variables:
DB_URL

The application exits immediately to prevent unsafe execution.

⚙️ API Reference

loadEnv(options)

Parameters

| Name | Type | Description | | -------- | ---------- | --------------------------------------------- | | required | string[] | List of environment variables that must exist | | defaults | object | Default values applied if variable is missing |

🧠 Real-World Example (Express.js)

import express from "express";
import { loadEnv } from "@hamzas07/smart-env";

loadEnv({
  required: ["PORT", "JWT_SECRET"],
  defaults: {
    PORT: 5000
  }
});

const app = express();

app.listen(process.env.PORT, () => {
  console.log("Server running");
});

🏗️ Use Cases

• Backend APIs
• Production deployments
• CI/CD pipelines
• Hackathon projects
• Open-source applications
• Enterprise Node.js services

🛣️ Roadmap

Planned improvements:

• [ ] .env file auto-loader
• [ ] TypeScript support
• [ ] CLI command (npx smart-env check)
• [ ] Framework presets (Express, Next.js)

Have a suggestion? Open an issue!

🤝 Contributing

Contributions are welcome.

1. Fork the repository
2. Create a new branch
3. Commit your changes
4. Open a pull request

📊 Package Information

👤 Author

Hamza Ansari Open-source contributor & full-stack developer

📜 License

MIT License © 2025