@axshat.co.in/env-safe

Fail-fast environment variable validation for Node.js applications.

@axshat.co.in/env-safe validates required environment variables at application startup, preventing silent runtime failures and misconfigurations.

Features

• Fail-fast on missing or invalid environment variables
• Runtime validation with clear error messages
• TypeScript-first with strong typing
• Zero dependencies
• Lightweight and fast
• Works with Node.js, Next.js, Vite, Express

Installation

npm install @axshat.co.in/env-safe

or

yarn add @axshat.co.in/env-safe

Code Examples

Basic usage

import { envSafe } from "@axshat.co.in/env-safe";

const env = envSafe({
  DATABASE_URL: "string",
  PORT: "number",
  DEBUG: "boolean",
});

Default values

const env = envSafe({
  PORT: { type: "number", default: 3000 },
});

Optional variables

const env = envSafe({
  LOG_LEVEL: { type: "string", optional: true },
});

Enum (restricted values)

const env = envSafe({
  NODE_ENV: {
    type: "enum",
    values: ["development", "production"],
  },
});

Custom validation

const env = envSafe({
  JWT_SECRET: {
    type: "string",
    validate: (value) => value.length >= 16,
  },
});

Real-world example

const env = envSafe({
  DATABASE_URL: "string",
  PORT: { type: "number", default: 3000 },
  NODE_ENV: {
    type: "enum",
    values: ["development", "production"],
  },
  JWT_SECRET: {
    type: "string",
    validate: (v) => v.length >= 16,
  },
});

TypeScript Interface

EnvType

export type EnvType = "string" | "number" | "boolean" | "enum";

EnvRule

export interface EnvRule<T = unknown> {
  type: EnvType;
  default?: T;
  optional?: boolean;
  values?: readonly string[];
  validate?: (value: T) => boolean;
}

EnvSchema

export type EnvSchema = Record<string, EnvType | EnvRule>;

envSafe signature

export function envSafe<T extends EnvSchema>(
  schema: T
): {
  [K in keyof T]: any;
};

Error Output

Missing variable:

❌ Missing environment variable: DATABASE_URL

Invalid value:

❌ Validation failed for: JWT_SECRET

Why @axshat.co.in/env-safe?

Accessing environment variables directly is unsafe:

process.env.API_KEY! // unsafe

This can lead to runtime crashes, silent bugs, and broken deployments.

@axshat.co.in/env-safe validates once, early, and clearly.

License

MIT © Akshat Singh

Contributing

Issues and pull requests are welcome. Please keep the package simple, lightweight, and dependency-free.