@munesoft/envx

One-line .env loader, validator, and type-safe config for Node.js.

---

Why envx?

Every Node.js app depends on environment variables — but most apps:

• Crash unexpectedly due to missing variables
• Treat everything as strings (even ports and flags)
• Lack validation and sensible defaults
• Fail silently in production

envx fixes this in one line.

---

Install

npm install @munesoft/envx

---

Quick Start

Add at the very top of your app:

import "@munesoft/envx/config";

Your .env file is now loaded, validated, and type-safe. That's it.

---

Basic Usage

.env

PORT=3000
NODE_ENV=development
API_KEY=sk_abc123

envx.config.js

export default {
  PORT:     { type: "number",  default: 3000 },
  NODE_ENV: { type: "string",  enum: ["development", "production"] },
  API_KEY:  { type: "string",  required: true },
};

app.js

import "@munesoft/envx/config";
// process.env.PORT is now the number 3000, not the string "3000"

---

API

import "@munesoft/envx/config" (recommended)

Side-effect import. Loads, validates, and applies env vars before your app runs. Uses envx.config.js if present, otherwise applies smart defaults.

---

import envx from "@munesoft/envx"

Programmatic loader with full options:

import envx from "@munesoft/envx";

await envx({
  path: ".env.production",       // custom .env path
  override: false,               // process.env wins by default
  debug: true,                   // print resolved values
  strict: true,                  // disallow unknown vars
  schema: {
    PORT:    { type: "number",  default: 3000 },
    API_KEY: { type: "string",  required: true },
  },
});

---

Schema Rules

Each key in the schema supports:

Option	Type	Description
type	string	One of string, number, boolean, url, email, json
required	boolean	Fail if the variable is missing
default	any	Value used when variable is absent
enum	any[]	Restrict to a fixed set of values
validate	function	Custom validator — return false or throw to fail

---

Supported Types

Type	Input example	Coerced to
string	"hello"	"hello"
number	"3000"	3000
boolean	"true", "1", "yes"	true
url	"https://..."	"https://..." (validated)
email	"a@b.com"	"a@b.com" (validated)
json	'{"a":1}'	{ a: 1 } (parsed)

---

Error Handling

envx fails fast with clear output:

❌ ENV VALIDATION FAILED

  - API_KEY is required but missing
  - PORT must be a number (received "abc")
  - NODE_ENV must be one of ["development", "production"] (received "staging")

---

Config Formats

Flat (simple):

export default {
  PORT:    { type: "number", default: 3000 },
  API_KEY: { type: "string", required: true },
};

Structured (with strict mode):

export default {
  strict: true,
  schema: {
    PORT:    { type: "number", default: 3000 },
    API_KEY: { type: "string", required: true },
  },
};

---

Advanced Features

Custom Validators

API_KEY: {
  type: "string",
  validate: (value) => value.startsWith("sk_"),
}

JSON Variables

FEATURE_FLAGS={"beta":true,"darkMode":false}

FEATURE_FLAGS: { type: "json" }
// → { beta: true, darkMode: false }

Environment-Specific Defaults

PORT: {
  type: "number",
  default: process.env.NODE_ENV === "production" ? 80 : 3000,
}

Debug Mode

ENVX_DEBUG=true node app.js

Prints resolved values at startup (secrets are masked automatically).

---

CLI

# Validate your .env against envx.config.js
npx envx check

# Validate a specific .env file
npx envx check --path .env.production

# Generate a starter config from your .env
npx envx init

---

TypeScript

envx ships with full type definitions:

import envx from "@munesoft/envx";
import type { LoadOptions, Schema } from "@munesoft/envx";

const schema: Schema = {
  PORT:    { type: "number",  default: 3000 },
  API_KEY: { type: "string",  required: true },
};

await envx({ schema });

const port: number = process.env.PORT as unknown as number;

---

Zero Config Mode

No envx.config.js? No problem.

envx will:

• Load .env automatically
• Apply smart defaults
• Warn on obviously missing critical variables

---

Security

• Prevents undefined variables from silently crashing apps
• Masks secrets in debug output (keys containing KEY, TOKEN, SECRET, PASSWORD)
• Encourages explicit, validated configuration

---

Philosophy

Configuration should never be a source of runtime failure.

envx ensures your app starts correctly or not at all.

---

vs dotenv

Feature	dotenv	envx
Load .env	✅	✅
Validation	❌	✅
Type coercion	❌	✅
Default values	❌	✅
Enum enforcement	❌	✅
Custom validators	❌	✅
Clear error output	❌	✅
TypeScript types	❌	✅
CLI tools	❌	✅
Zero-config mode	❌	✅

---

License

MIT © Munesoft