super-env

A secure, batteries-included environment variable toolkit for Node.js. Drop-in replacement for dotenv with cascading, type coercion, encryption, and more.

Features

• Drop-in dotenv replacement - Works with existing code
• Cascading file discovery - Perfect for monorepos
• JSON config support - Flatten nested JSON to env vars
• Type coercion - int, float, bool, date, json, array, url, port, enum
• Variable interpolation - ${VAR} and ${VAR:-default}
• AES-256-GCM encryption - Secure your .env files
• Secret detection - Scan for leaked secrets
• Value redaction - Mask secrets in logs
• File watching - Hot-reload on changes
• Type generation - Generate TypeScript from .env
• CLI tools - encrypt, decrypt, scan, diff, and more

Installation

npm install super-env

Quick Start

// Drop-in replacement for dotenv
import { config } from 'super-env';
config();

// Or with full features
import { loadEnv } from 'super-env';

const { env } = loadEnv({
  depth: -1,                      // Traverse up to monorepo root
  stopAt: 'pnpm-workspace.yaml',
  files: ['.env', 'config.json'],
  json: { flatten: 'uppercase' },
});

// Typed access
const port = env.port('PORT', 3000);
const debug = env.bool('DEBUG', false);
const hosts = env.array('ALLOWED_HOSTS', ',');

CLI

super-env check .env          # Validate env file
super-env scan .env           # Detect secrets
super-env encrypt .env        # Encrypt file
super-env decrypt .env.enc    # Decrypt file
super-env types .env          # Generate TypeScript
super-env diff .env .env.prod # Compare files

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Installation and basic usage | | Type Coercion | Typed env accessors | | Cascading | Monorepo and multi-file support | | JSON Config | Loading JSON configuration files | | Interpolation | Variable references | | Encryption | Encrypting env files | | Secret Detection | Scanning for secrets | | Redaction | Masking sensitive values | | File Watching | Hot-reload support | | Type Generation | TypeScript/JS codegen | | CLI Reference | Command-line tools | | API Reference | Full API documentation |

License

MIT