@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 | "[email protected]" | "[email protected]" (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