npm package: @href00/envx
Description: Dynamic environment loader for Node.js applications with nodemon integration
Author: hrefdev
Latest version: 0.2.3

# envx - Zero-Setup Environment Loader

[![npm version](https://img.shields.io/npm/v/@href00/envx.svg)](https://www.npmjs.com/package/@href00/envx)
[![npm downloads](https://img.shields.io/npm/dm/@href00/envx.svg)](https://www.npmjs.com/package/@href00/envx)
[![GitHub Stars](https://img.shields.io/github/stars/href0/envx.svg)](https://github.com/href0/envx/stargazers)
[![GitHub Issues](https://img.shields.io/github/issues/href0/envx.svg)](https://github.com/href0/envx/issues)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js CI](https://github.com/href0/envx/workflows/CI/badge.svg)](https://github.com/href0/envx/actions)

**Environment variables without the hassle** - No installation, no imports, no configuration required.

A lightweight, dynamic environment variable loader for Node.js applications that works with any existing project without code modifications.

🌐 **[Documentation Website](https://href0.github.io/envx/)** | 📦 **[NPM Package](https://www.npmjs.com/package/@href00/envx)** | 🐛 **[Report Issues](https://github.com/href0/envx/issues)**

## 🎯 Why envx?

**The Problem with Other Solutions:**
```javascript
// ❌ Other tools require code modification
require('dotenv').config();           // dotenv
require('dotenv-flow').config();      // dotenv-flow  
const env = require('env-var');       // env-var

// ❌ Or require project installation
npm install dotenv-cli                // dotenv-cli
dotenv -e .env.dev -- node app.js
```

**The envx Solution:**
```bash
# ✅ Works with ANY existing Node.js project
# ✅ NO code modification needed
# ✅ NO project dependencies required

npx @href00/envx your-app.js --env=dev
```

## ✨ Features

- 🎪 **Zero Setup**: Works with any existing Node.js project instantly
- 🔧 **No Code Changes**: Your application code stays exactly the same
- 🔄 **Environment Overlays**: Base `.env` + environment-specific files (`.env.dev`, `.env.staging`)
- 🚀 **Nodemon Integration**: Built-in auto-reload with `envx-nodemon`
- 🛡️ **Production Safe**: Configurable loading in CI/production environments
- 📦 **Zero Dependencies**: Lightweight with built-in dotenv parser
- 🏗️ **Legacy Friendly**: Perfect for projects that can't be modified

## 🚀 Quick Start

### **Option 1: 🌍 Global Install (Recommended)**
```bash
# Install once, use everywhere
npm install -g @href00/envx

# Then use directly without npx
envx your-app.js --env=dev
envx-nodemon your-app.js --env=dev
```

### **Option 2: 📦 Project Install**
```bash
# Install in your project
npm install --save-dev @href00/envx

# Add to package.json scripts
{
  "scripts": {
    "dev": "envx-nodemon server.js --env=dev",
    "start": "envx server.js --env=prod"
  }
}

# Run via npm
npm run dev
```

### **Option 3: 🔄 Direct npx (No Installation)**
```bash
# Use directly (will prompt for installation)
npx @href00/envx your-app.js --env=dev

# Skip confirmation with --yes
npx --yes @href00/envx your-app.js --env=dev
npx --yes --package=@href00/envx envx-nodemon your-app.js --env=dev
```

## 💡 Usage

### Instant Environment Loading

```bash
# Works with ANY existing Node.js project
npx @href00/envx your-app.js              # Load .env
npx @href00/envx your-app.js --env=dev    # Load .env + .env.dev
npx @href00/envx your-app.js --env=prod   # Load .env + .env.prod

# With nodemon integration
npx --package=@href00/envx envx-nodemon server.js --env=dev    # Auto-reload development
```

### Perfect for Legacy Projects

```bash
# Got an old project that can't be modified? No problem!
npx @href00/envx legacy-app.js --env=production

# No need to add require() statements
# No need to install dependencies  
# Just works!
```

### Command Line Reference

```bash
npx @href00/envx <entry.js> [options] -- [app-arguments]

Options:
  --env=<name>      Load environment-specific overlay (.env.<name>)
  --allow-ci        Allow loading env files in CI environment
  --allow-prod      Allow loading env files in production
  --quiet           Suppress envx output messages

Examples:
  npx @href00/envx app.js --env=dev
  npx @href00/envx app.js --env=staging --quiet
  npx @href00/envx app.js --env=prod --allow-prod -- --port=3000
  npx --package=@href00/envx envx-nodemon server.js --env=dev --watch src
```

## 🔄 Environment Overlay System

### Environment File Structure

```
.env              # Base environment (always loaded first)
.env.dev          # Development overlay
.env.staging      # Staging overlay
.env.production   # Production overlay
```

### Example `.env` files

**.env** (base):
```env
DATABASE_URL=postgresql://localhost:5432/myapp
API_KEY=base-api-key
NODE_ENV=development
```

**.env.dev** (development overlay):
```env
DATABASE_URL=postgresql://dev-server:5432/myapp_dev
API_KEY=dev-api-key-override
REDIS_URL=redis://dev-redis:6379
```

**.env.staging** (staging overlay):
```env
DATABASE_URL=postgresql://staging-server:5432/myapp_staging
API_KEY=staging-api-key
NODE_ENV=staging
```

## Integration with Nodemon

envx provides seamless integration with nodemon for development with auto-reload functionality.

### Built-in envx-nodemon

```bash
# Zero-setup auto-reload development
npx --package=@href00/envx envx-nodemon server.js --env=dev

# With additional nodemon options
npx --package=@href00/envx envx-nodemon server.js --env=dev -- --watch src --ext js,mjs,json

# Different environments with auto-reload
npx --package=@href00/envx envx-nodemon server.js --env=staging
npx --package=@href00/envx envx-nodemon server.js --env=prod --allow-prod
```

## 🥊 vs Other Solutions

| Feature | **envx** | dotenv | dotenv-cli | env-var |
|---------|----------|--------|------------|---------|
| **Code modification required** | ❌ None | ✅ Yes | ❌ None | ✅ Yes |
| **Project installation needed** | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes |
| **Works with legacy projects** | ✅ Perfect | ❌ No | ✅ Limited | ❌ No |
| **Environment overlays** | ✅ Built-in | ❌ No | ❌ No | ❌ No |
| **Nodemon integration** | ✅ Built-in | ❌ Manual | ❌ Manual | ❌ Manual |
| **Zero dependencies** | ✅ Yes | ✅ Yes | ❌ No | ❌ No |

### Migration Examples

**From dotenv:**
```javascript
// Before (requires code changes)
require('dotenv').config();
const app = require('./app');

// After (no code changes needed)
// Just run: npx @href00/envx app.js --env=dev
const app = require('./app');  // Same code!
```

**From dotenv-cli:**
```bash
# Before
npm install dotenv-cli
dotenv -e .env.dev -- node app.js

# After  
npx @href00/envx app.js --env=dev
```

## 🎯 Perfect Use Cases

### 🏗️ Legacy Projects
```bash
# Got a 5-year-old Node.js project that can't be touched?
npx @href00/envx old-app.js --env=production
# No refactoring needed!
```

### 🚀 Rapid Prototyping  
```bash
# Quick proof of concept - no setup time
npx @href00/envx prototype.js --env=dev
```

### 👥 Team Demos
```bash
# Show different environments instantly
npx @href00/envx demo.js --env=demo-client-a
npx @href00/envx demo.js --env=demo-client-b
```

### 🔄 CI/CD Scripts
```bash
# Clean environment control in pipelines
npx @href00/envx deploy.js --env=staging --allow-ci
```

### 🏢 Microservices
```bash
# Consistent environment loading across services
npx @href00/envx user-service.js --env=dev
npx @href00/envx order-service.js --env=dev  
npx @href00/envx payment-service.js --env=dev
```

### Package.json Scripts Integration

Add these scripts to your `package.json`:

```json
{
  "scripts": {
    "dev": "npx --package=@href00/envx envx-nodemon server.js --env=dev",
    "dev:staging": "npx --package=@href00/envx envx-nodemon server.js --env=staging", 
    "dev:debug": "npx --package=@href00/envx envx-nodemon server.js --env=dev -- --verbose",
    "start": "npx --package=@href00/envx envx server.js --env=prod --allow-prod",
    "test": "npx --package=@href00/envx envx test-runner.js --env=test"
  }
}
```

**Alternative (if installed globally):**
```json
{
  "scripts": {
    "dev": "envx-nodemon server.js --env=dev",
    "dev:staging": "envx-nodemon server.js --env=staging", 
    "dev:debug": "envx-nodemon server.js --env=dev -- --verbose",
    "start": "envx server.js --env=prod --allow-prod",
    "test": "envx test-runner.js --env=test"
  }
}
```

Then run:
```bash
npm run dev              # Development with auto-reload
npm run dev:staging      # Staging with auto-reload  
npm run start           # Production without auto-reload
npm test               # Test environment
```

## 🔧 Advanced Usage

### Nodemon Integration Options

```bash
# Watch specific directories
npx --package=@href00/envx envx-nodemon server.js --env=dev -- --watch src --watch config

# Custom file extensions  
npx --package=@href00/envx envx-nodemon server.js --env=dev -- --ext js,mjs,ts,json

# Delay restart (useful for compilation)
npx --package=@href00/envx envx-nodemon server.js --env=dev -- --delay 2.5

# Ignore files/directories
npx --package=@href00/envx envx-nodemon server.js --env=dev -- --ignore tests/ --ignore docs/

# Environment file watching
npx --package=@href00/envx envx-nodemon server.js --env=dev -- --watch .env*
```

## 📁 File Structure & Examples

**Project Structure:**
```
my-app/
├── .env              # Base config
├── .env.dev          # Development overrides
├── .env.staging      # Staging overrides
├── .env.prod         # Production config
├── server.js         # Your application
├── package.json      # Scripts and dependencies
└── nodemon.json      # Nodemon configuration (optional)
```

**Environment Files:**
```env
# .env (base)
DATABASE_URL=postgresql://localhost:5432/myapp
PORT=3000
NODE_ENV=development

# .env.dev (development)
DATABASE_URL=postgresql://localhost:5432/myapp_dev
PORT=3001
DEBUG=true
LOG_LEVEL=debug

# .env.staging (staging)
DATABASE_URL=postgresql://staging-db:5432/myapp_staging
PORT=3002
NODE_ENV=staging
LOG_LEVEL=warn

# .env.prod (production)
DATABASE_URL=postgresql://prod-db:5432/myapp_production
PORT=3000
NODE_ENV=production
LOG_LEVEL=error
```

**Development Workflow:**
```bash
# Start development with auto-reload
npm run dev
# → Loads .env + .env.dev
# → Starts server on port 3001  
# → Auto-reloads on file changes
# → Debug logging enabled

# Test staging environment
npm run dev:staging  
# → Loads .env + .env.staging
# → Starts server on port 3002
# → Auto-reloads on file changes
# → Staging database connection

# Production deployment  
npm start
# → Loads .env + .env.prod
# → Starts server on port 3000
# → No auto-reload
# → Minimal logging
```

## 🛠️ How It Works

1. **Base Loading**: Always loads `.env` first (if exists)
2. **Overlay Loading**: Loads environment-specific file (`.env.<env>`) which overrides base values  
3. **Environment Injection**: Sets all variables in `process.env`
4. **App Execution**: Runs your application with the loaded environment

## 🛡️ Safety Features

- **CI Protection**: Automatically skips file loading in CI environments (unless `--allow-ci`)
- **Production Protection**: Skips file loading when `NODE_ENV=production` (unless `--allow-prod`)  
- **Argument Passing**: Cleanly passes arguments to your application via `--`
- **Error Handling**: Graceful fallback when environment files don't exist

## 🧪 Testing

```bash
# Run automated tests
npm test

# Manual testing with different environments
npm run test:manual
```

## 📊 Package Stats

- **Size**: < 50KB unpacked
- **Dependencies**: Zero runtime dependencies  
- **Node.js**: >= 14.0.0
- **License**: MIT
- **Downloads**: Growing daily! 📈

## 📈 Repository Stats

![GitHub repo size](https://img.shields.io/github/repo-size/href0/envx)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/href0/envx)
![GitHub top language](https://img.shields.io/github/languages/top/href0/envx)
![GitHub last commit](https://img.shields.io/github/last-commit/href0/envx)

## 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=href0/envx&type=Date)](https://star-history.com/#href0/envx&Date)

## 🔗 Related Projects

- [dotenv](https://github.com/motdotla/dotenv) - Original .env file loader
- [dotenv-cli](https://github.com/entropitor/dotenv-cli) - CLI for dotenv
- [nodemon](https://github.com/remy/nodemon) - Auto-restart development tool

## 🤝 Contributing

Contributions welcome! Please read our [contributing guidelines](CONTRIBUTING.md) and submit pull requests to our [repository](https://github.com/href0/envx).

## 📝 License

MIT - see [LICENSE](LICENSE) file for details.

---

**Made with ❤️ for developers who value simplicity**

*"Environment variables without the hassle"* - that's the envx promise!