envf — Minimal, Smart, Zero-Bullshit Environment Loader

A lightweight .env loader designed for real-world Node.js apps — automatic environment detection, layered env loading, optional overrides, and a clean API.

No dependencies. No magic. Just predictable behavior.

🚀 Features

• Auto-loads env files based on environment mode:

  • .env.development.local
  • .env.local
  • .env.development
  • .env

• Supports manual single-file loading via load()

• Injects values directly into process.env

• Override behavior configurable (override: true | false)

• Zero surprises path resolution (cwd > fallback-to-module)

• Debug helpers (see(), keys())

📦 Installation

npm install envf

or

pnpm add envf

🎯 Quick Usage

Auto mode

(recommended — handles NODE_ENV logic)

import envf from "envf";

envf.autoLoad();

console.log(process.env.PORT);
console.log(process.env.DB_URL);

Works immediately with zero configuration.

Manual load (single file)

import envf from "envf";

envf.load(".env"); // resolves path automatically

Load an absolute file path

envf.pathLoad("/etc/app/secrets.env");

Inject manually

envf.setKey("PORT"); // one
envf.setKeys(["PORT", "DB_URL"]); // many

With override:

envf.setKeys(["PORT", "DB_URL"], { override: true });

Get values

const db = envf.getKey("DB_URL");

Debugging

envf.keys(); // show injected keys
envf.see();  // show loaded files

🧠 Environment Loading Priority

When calling autoLoad(), files are loaded in this order (first found → overrides later ones):

.env.<NODE_ENV>.local
.env.local
.env.<NODE_ENV>
.env

For example: running with:

NODE_ENV=production

Load order becomes:

.env.production.local
.env.local
.env.production
.env

🛠 API Summary

| Method | Purpose | | ------------------------- | ------------------------------------ | | load(file) | Load a specific env file | | autoLoad(options?) | Auto load layered env files | | pathLoad(path) | Load env from an explicit path | | setKey(key) | Inject a single key into process.env | | setKeys(keys, options?) | Bulk inject multiple keys | | getKey(key) | Retrieve a value | | keys() | Show injected keys | | see() | Show loaded files |

🧭 Changelog

v1.x.x — Initial Implementation

• Basic .env loading
• Basic parsing and manual injection
• No override logic
• No layering or environment detection

v2.x.x — Layered Environment & Auto Loading

• Added autoLoad() with multi-file loading support
• Added path resolution (cwd → fallback)
• Added automatic injection behavior
• Added multiple env file support (.env.local, .env.NODE_ENV, etc.)

v3.x.x — Configurable Injection & Better DX

• Added setKeys() with optional { override: boolean }
• Added getKey(), keys(), and see() for debugging and introspection
• Improved logging accuracy
• Added validation for invalid key names
• Stabilized module export structure and path resolution logic

v3.1.x — Refinement & Stability

• API consistency cleanup
• Logging and behavior now fully deterministic
• Internal path resolution improvements
• Polished for npm release

📌 License

LICENSE — build cool shit, don’t use it for malware, and don’t pretend you wrote it.

💬 Contributing

PRs welcome — just don’t break the API and keep it clean.