envx - Zero-Setup Environment Loader

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 | 📦 NPM Package | 🐛 Report Issues

🎯 Why envx?

The Problem with Other Solutions:

// ❌ 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:

# ✅ 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)

# 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

# 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)

# 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

# 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

# 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

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):

DATABASE_URL=postgresql://localhost:5432/myapp
API_KEY=base-api-key
NODE_ENV=development

.env.dev (development overlay):

DATABASE_URL=postgresql://dev-server:5432/myapp_dev
API_KEY=dev-api-key-override
REDIS_URL=redis://dev-redis:6379

.env.staging (staging overlay):

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

# 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:

// 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:

# 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

# 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

# Quick proof of concept - no setup time
npx @href00/envx prototype.js --env=dev

👥 Team Demos

# 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

# Clean environment control in pipelines
npx @href00/envx deploy.js --env=staging --allow-ci

🏢 Microservices

# 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:

{
  "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):

{
  "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:

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

# 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 (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:

# 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

# 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

🌟 Star History

🔗 Related Projects

• dotenv - Original .env file loader
• dotenv-cli - CLI for dotenv
• nodemon - Auto-restart development tool

🤝 Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests to our repository.

📝 License

MIT - see LICENSE file for details.

Made with ❤️ for developers who value simplicity

"Environment variables without the hassle" - that's the envx promise!