npm package: @hamzas07/smart-env
Description: Minimal environment loader and validator
Author: Hamza Ansari
Latest version: 1.0.2

# 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

```bash
npm install @hamzas07/smart-env
```

---

## 🚀 Quick Start

```js
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)

```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

![npm version](https://img.shields.io/npm/v/@hamzas07/smart-env)
![npm downloads](https://img.shields.io/npm/dw/@hamzas07/smart-env)
![license](https://img.shields.io/npm/l/@hamzas07/smart-env)

---

## 👤 Author

**Hamza Ansari**
Open-source contributor & full-stack developer

---

## 📜 License

MIT License © 2025