smart-env

Zero-config environment variable loader + validator for Node.js.

Installation

npm install smart-env

Zero-Config Usage

For zero-config loading of environment variables:

import "smart-env/register";

This automatically loads environment variables from .env files in the following order:

• .env
• .env.local
• .env.{NODE_ENV} (e.g., .env.development)
• .env.{NODE_ENV}.local (e.g., .env.development.local)

Later files override earlier ones. The loaded variables are merged into process.env.

Config Usage

For advanced usage with validation:

import { loadEnv } from "smart-env";

const env = loadEnv({
  PORT: { type: "number", required: true },
  DEBUG: { type: "boolean", default: false },
  NODE_ENV: { type: "enum", values: ["development", "production"] }
});

This validates environment variables according to the provided schema. Supported types:

• string: Any string value
• number: Numeric values (rejects NaN and empty strings)
• boolean: true, false, 1, 0
• enum: One of the specified values

If required is true or no default is provided, the variable must be present.

If validation fails, it prints a clear error message and exits with code 1.

Error Output

When validation fails, you'll see output like:

❌ ENV VALIDATION FAILED

Missing:
  - DATABASE_URL

Invalid:
  - PORT → expected number, got "abc"

Fix:
  DATABASE_URL=...
  PORT=123