envforge

the config manager that actually gets it
no more "works on my machine" because someone forgot to add API_KEY to .env

ever pushed to prod and realized your app crashed because DATABASE_URL was missing? yeah we've all been there. this lib makes sure that NEVER happens again.

why tho?

most env libraries be like:

• load .env ✓
• thats it 💀

envforge be like:

• validate everything before your app even starts ✓
• auto-detect secrets and mask them in logs ✓
• hot reload in dev so you dont restart 47 times ✓
• CLI to check/generate/audit your envs ✓

install

npm install envforge
# or
yarn add envforge
# or 
pnpm add envforge

the vibe (quick start)

import { forge, str, num, bool, secret } from 'envforge';

const config = forge({
  schema: {
    // clean builder API
    dbHost: str().default('localhost'),
    port: num().default(3000),
    apiKey: secret(str()),  // auto-masked in logs
    debug: bool().default(false)
  }
});

// this throws IMMEDIATELY if something's wrong
// no more finding out in production lmao

CLI go brrr

# check if ur env valid
$ npx envforge check

✔ .env loaded
✔ schema validated  
✔ 8 variables OK
⚠ 1 secret detected (make sure its in .gitignore fr)

# generate .env.example automatically
$ npx envforge generate

# Generated by envforge
DB_HOST=localhost
DB_PORT=5432
API_KEY=          # (secret - fill this in)

# security audit (finds sketchy stuff)
$ npx envforge audit

⚠ 2 issues found:
  • API_KEY is too short (brute force go brrr)
  • .env not in .gitignore (ur gonna leak secrets bro)

# auto-generate docs
$ npx envforge docs

# outputs CONFIGURATION.md with table of all env vars

whats different?

feature	dotenv	envalid	envforge
validation	❌	✅	✅
CLI tools	❌	❌	✅
secret masking	❌	❌	✅
hot reload	❌	❌	✅
auto docs	❌	❌	✅
security audit	❌	❌	✅
zero deps	✅	✅	✅

basically we took everything annoying about env management and yeeted it out the window

the API hits different

builder pattern (clean af)

import { str, num, bool, url, email, port, secret } from 'envforge';

const config = forge({
  schema: {
    host: str().default('localhost'),
    port: num().default(3000),
    apiUrl: url().required(),
    webhook: url().secret(),  // masked in logs
    adminEmail: email().default('admin@example.com'),
    serverPort: port().default(8080),
    debug: bool().default(false)
  }
});

hot reload (dev mode only)

const config = forge({
  schema: { ... },
  watch: true,  // auto reload when .env changes
  onReload: (vals) => console.log('config updated:', vals),
  onError: (err) => console.error('reload failed:', err)
});

secret handling (no leaks)

const config = forge({
  schema: {
    apiKey: secret(str()),     // explicit
    dbPassword: str()          // auto-detected (has 'password')
  }
});

// secrets get [REDACTED] automatically
console.log(config.toJSON());
// { "apiKey": "[REDACTED]", "dbPassword": "[REDACTED]" }

// but u can still use them
fetch('/api', { 
  headers: { 'X-API-Key': config.get('apiKey') } 
});

supported types

type	example
str()	any string
num()	integers, floats
bool()	true/false/1/0/yes/no
url()	valid URLs
email()	email format
port()	1-65535
json<T>()	parsed JSON

security stuff (important fr)

• auto detects secrets by key name (key, secret, password, token, auth, etc)
• masks them in all JSON output
• CLI audit finds weak secrets
• warns if .env not in .gitignore
• scans for hardcoded secrets in source files

requirements

• node 18+ (we use native fs.watch)
• ES modules (type: "module" in package.json)

license

MIT - do whatever just dont blame me if u leak ur aws keys 💀