smart-envx

A modern .env manager for Node.js — loads, validates, and auto-generates .env.example files with support for defaults, type checking, and environment-based loading.

Features

Load .env or .env.{mode} files easily
Fallback defaults if variables are missing
Validate environment variables with type checking
Auto-generate .env.example from loaded env
Support for dev / prod modes automatically
Lightweight — zero dependencies except dotenv
Simple API, TypeScript-friendly

Installation

npm install smart-envx

Or if you’re using Yarn:

yarn add smart-envx

Quick Example

const {
  loadEnv,
  validate,
  generateExample,
  loadByMode,
} = require("smart-envx");

// Load .env or .env.development automatically
loadByMode({
  PORT: "3000",
  DB_URL: "http://localhost:5000",
  DEBUG_MODE: "false",
});

// Validate required variables
validate(["PORT", "DB_URL"], {
  PORT: "number",
  DB_URL: "url",
  DEBUG_MODE: "boolean",
});

// Generate .env.example automatically
generateExample();

⚙️ API Reference

1 loadEnv(path = '.env', defaults = {})

Loads environment variables from a .env file and applies default values if missing.

loadEnv(".env", { PORT: "8080", MODE: "development" });

🟢 If .env file doesn’t exist, it uses existing process.env values or defaults.

2 validate(requiredVars, schema)

Validates presence and types of required environment variables.

Supported types:

• string
• number
• boolean
• url

validate(["PORT", "API_KEY"], { PORT: "number", API_KEY: "string" });

❌ If any variable is missing or has the wrong type, it logs an error and stops the process.

3 generateExample(filePath = '.env.example')

Automatically generates (or updates) an .env.example file with all current environment keys.

generateExample();

4 loadByMode(defaults = {})

Automatically loads .env.development or .env.production based on your NODE_ENV.

process.env.NODE_ENV = "production";
loadByMode({ PORT: "4000" }); // loads .env.production

If NODE_ENV isn’t set, it defaults to development.

Example Folder Structure

project/
├── .env.development
├── .env.production
├── .env.example
├── index.js
└── package.json

Example .env file

PORT=4000
DB_URL=https://example.com/db
DEBUG_MODE=true

Example Output

When you run your app:

 Loading environment: development
 Applied default: DB_URL=http://localhost:5000
Environment variables validated successfully!
Example .env file generated at .env.example

Why Use smart-envx?

| Problem | Solution | | ---------------------------------- | ----------------------------------------------- | | Missing .env variables crash app | Automatically applies safe defaults | | No clear .env.example | Auto generates and syncs one | | Hard to validate env types | Built-in type validator | | Switching between dev/prod | loadByMode() loads correct file automatically |

Author

Developed with by Saad

GitHub: @saad npm: @nextgen78

License

MIT License — free to use, modify, and distribute.

Support the Project

If you like smart-envx, consider:

• ⭐ Starring the repo on GitHub
• 🐦 Sharing it on Twitter / LinkedIn
• 💡 Using it in your open-source projects!