ultraenv

╔═══════════════════════════════════════════════════╗
║                                                   ║
║     ██████╗ ██████╗ ███████╗██╗  ██╗██╗  ██╗     ║
║    ██╔════╝██╔═══██╗██╔════╝██║ ██╔╝██║ ██╔╝     ║
║    ██║     ██║   ██║███████╗█████╔╝ █████╔╝      ║
║    ██║     ██║   ██║╚════██║██╔═██╗ ██╔═██╗      ║
║    ╚██████╗╚██████╔╝███████║██║  ██╗██║  ██╗     ║
║     ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝     ║
║                                                   ║
║   The Ultimate Environment Variable Manager        ║
║   v1.0.0                                          ║
╚═══════════════════════════════════════════════════╝

Validate, Type, Encrypt, Sync, and Never Ship Broken Configs Again.

Getting Started · Schema Reference · CLI Reference · Vault Guide · Docs

🤔 Why ultraenv?

Every project uses environment variables. Every project gets them wrong eventually.

• Missing variables crash production at 3 AM.
• Wrong types (process.env.PORT is always a string) cause silent bugs.
• Leaked secrets in .env files end up in git history forever.
• Drifting .env.example files lead to confusing onboarding for new developers.
• No validation means you find out about missing configs at runtime.

ultraenv solves all of these problems with a single, zero-dependency library that provides:

Problem	ultraenv Solution
No type safety for process.env	Full TypeScript inference from schema
Secrets leaked in git	Built-in secret scanner with 55+ patterns
No .env validation	Schema engine with 30+ validators
Secrets in plain text	AES-256-GCM encrypted vault
.env.example out of sync	Auto-sync with watch mode
No multi-environment support	Multi-env management (dev, staging, prod)
Can't use in CI/CD	CI commands with SARIF output
Hard to migrate from dotenv	Drop-in replacement with load()

📊 Feature Comparison

Feature	ultraenv	dotenv	envalid	@t3-oss/env
Parse .env files	✅	✅	✅	✅
TypeScript inference	✅ Full	❌	✅ Partial	✅ Full
Schema validators	✅ 30+	❌	✅ 8	✅ Via zod
String validators	✅ 20+	❌	❌	Via zod
Secret scanning	✅ 55+ patterns	❌	❌	❌
Encrypted vault	✅ AES-256-GCM	❌	❌	❌
Key rotation	✅	❌	❌	❌
.env.example sync	✅ Watch mode	❌	❌	❌
Type generation	✅ .d.ts / module / JSON Schema	❌	❌	✅
Multi-environment	✅ 11 file variants	❌	❌	❌
Framework presets	✅ 9 presets	❌	❌	❌
CI/CD integration	✅ SARIF output	❌	❌	❌
Variable interpolation	✅ $VAR / ${VAR}	✅	❌	❌
File cascade	✅ Priority-based	❌	❌	❌
Hot reload watcher	✅	❌	❌	❌
Health check API	✅	❌	❌	❌
Express middleware	✅	❌	❌	❌
Fastify plugin	✅	❌	❌	❌
SARIF output	✅	❌	❌	❌
Git hook integration	✅	❌	❌	❌
dotenv-compatible API	✅	—	❌	❌
Zero dependencies	✅	✅	❌	❌
Node.js	≥ 18	≥ 12	≥ 14	≥ 18

🚀 Quick Start

Get started in three steps:

Step 1 — Install

npm install ultraenv

Step 2 — Define your schema

Create an env.ts file:

import { defineEnv, t } from 'ultraenv';

const env = defineEnv({
  DATABASE_URL: t.string().format('url').required(),
  PORT: t.number().port().default(3000),
  NODE_ENV: t.enum(['development', 'staging', 'production'] as const).required(),
  DEBUG: t.boolean().default(false),
  ADMIN_EMAIL: t.email().optional(),
  ALLOWED_ORIGINS: t.array().separator(';').default(['http://localhost:3000']),
  CACHE_TTL: t.duration().default('1h'),
  MAX_UPLOAD_SIZE: t.bytes().default('10MB'),
});

export default env;

Step 3 — Use your typed env everywhere

import env from './env';

const server = createServer({
  port: env.PORT,           // number
  host: env.HOST,           // string
  databaseUrl: env.DATABASE_URL,
});

📦 Installation

npm install ultraenv
pnpm add ultraenv
yarn add ultraenv
bun add ultraenv

Global CLI

npm install -g ultraenv
ultraenv init
ultraenv validate
ultraenv scan

🔧 CLI Command Reference

Command	Description
ultraenv init	Initialize project
ultraenv validate	Validate environment variables
ultraenv typegen	Generate TypeScript types
ultraenv sync	Sync .env.example
ultraenv scan	Scan for leaked secrets
ultraenv debug	Show diagnostics
ultraenv protect	Check .gitignore protection
ultraenv doctor	Run self-checks
ultraenv vault *	Vault encrypt/decrypt/rekey
ultraenv envs *	Multi-environment management
ultraenv ci *	CI/CD integration commands

📐 Schema Reference

All schema builders via the t factory:

import { defineEnv, t } from 'ultraenv';

t.string().format('url').required()
t.number().port().default(3000)
t.boolean().default(false)
t.enum(['a', 'b'] as const).required()
t.url({ protocols: ['https'] }).required()
t.email().optional()
t.array().separator(';').trimItems().required()
t.json<{ theme: string }>().required()
t.duration().default('1h')
t.bytes().default('10MB')
t.path({ mustExist: false }).default('./uploads')
t.uuid({ version: 4 }).required()
t.ip().required()
t.cron().default('0 2 * * *')

🔐 Encryption & Vault

ultraenv vault init --env production
ultraenv vault encrypt --env production
git add .env.vault  # safe to commit!
ultraenv vault decrypt --env production

• Algorithm: AES-256-GCM
• .env.vault → commit ✅
• .env.keys → gitignore ❌

🔍 Secret Scanning

ultraenv scan                          # Scan files
ultraenv scan --scope git-history      # Scan git history
ultraenv scan --format sarif --output results.sarif  # GitHub Code Scanning

55+ patterns: AWS, GitHub, Google, Stripe, Slack, private keys, DB URLs, and more.

🤝 Contributing

git clone https://github.com/Avinashvelu03/ultraenv.git
cd ultraenv && npm install
npm test
npm run build

📜 License

MIT © 2024 Avinash Velu

🔐 Support ultraenv

  ██████╗  ██████╗ ███╗   ██╗ █████╗ ████████╗███████╗
  ██╔══██╗██╔═══██╗████╗  ██║██╔══██╗╚══██╔══╝██╔════╝
  ██║  ██║██║   ██║██╔██╗ ██║███████║   ██║   █████╗
  ██║  ██║██║   ██║██║╚██╗██║██╔══██║   ██║   ██╔══╝
  ██████╔╝╚██████╔╝██║ ╚████║██║  ██║   ██║   ███████╗
  ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝   ╚═╝   ╚══════╝

ultraenv is solo-built and freely available to every developer on Earth. If it saved your secrets, saved your sanity, or caught a leak before prod — it earned your support.

Zero-cost support:

• ⭐ Star on GitHub
• 🐛 Report a bug or request a feature
• 📣 Share ultraenv with your team or in your community

Made with ❤️ by Avinash Velu

Report Bug · Request Feature · Discussions