v2.0.0 is now live

env-typed-guard

Type-safe environment variables. Validate at runtime.
Fail fast in production.

import { defineEnv } from "env-typed-guard";

const env = defineEnv({
  PORT: { type: "number", defaultValue: 3000 },
  DATABASE_URL: { type: "string" },
  DEBUG: { type: "boolean", defaultValue: false },
});

Environment variables break
production apps silently.

There is no TypeScript safety for process.env — until now.

Missing env vars

Applications crash at runtime when required variables are forgotten.

Silent Typos

Minor spelling mistakes in .env files lead to hours of debugging.

Production Risks

Teams ship broken configurations unknowingly, risking uptime.

A runtime safety layer for
configuration correctness.

Schema-based environment definition

Runtime validation at app startup

Strict typing with TypeScript inference

Fail-fast behavior (Process exit on invalid env)

Optional debug logging & masking

Custom validation & enum support

runtime_validation.ts

// Reading .env...

PORT: 3000 ✓ valid

DATABASE_URL: "postgres://..." ✓ valid

NODE_ENV: "production" ✓ valid

Status: App starting with validated config.

Built for modern backend teams

Everything you need to ship confident Node.js applications.

Type-safe env access

Get full IntelliSense and compile-time safety for your environment variables.

Fail-fast validation

Stop the application immediately if any required config is missing or invalid.

Full TypeScript inference

Automatically derive types from your schema without manual interface definitions.

Runtime validation engine

Strict type checking for numbers, booleans, and enums at process startup.

Enum & Custom validation

Define valid values or custom logic to ensure data integrity.

Zero-dependency core

Lightweight and secure. No external bloat added to your production binary.

defineEnv(schema, config?)

The primary entry point. Define your environment schema once and get a validated, typed object for your entire application.

Supported Types

string

Basic string validation

number

Automatically parses strings to numbers

boolean

Supports 'true', 'false', '1', '0' with truthy/falsy parsing

enum

Validate against a fixed set of values

Extra Features

defaultValue

Fallback if variable is not provided

validate

Custom function for complex logic

key

Map current key to a different process.env key

isSecret

Masks values in debug logs

import { defineEnv } from "env-typed-guard";

const env = defineEnv({
  NODE_ENV: {
    type: "enum",
    validValues: ["dev", "prod", "test"],
    defaultValue: "dev",
  },
  PORT: { 
    type: "number", 
    defaultValue: 3000,
    validate: (v) => v > 1024 
  },
  DB_URL: { 
    type: "string", 
    isSecret: true 
  },
});

Full IntelliSense based on your schema definition.

Instant Clarity on Errors

Stop guessing why your deployment failed. Get human-readable error logs.

Debug Console

[11:34:33 PM]ERROREnvMissing: DATABASE_URL is required but was not found in process.env

[11:34:33 PM]ERROREnvInvalidType: PORT must be a number (received: "abc")

[11:34:33 PM]ERROREnvInvalidPossibility: NODE_ENV value "staging" is not allowed

_ Process exited with code 1

Important: Node.js vs Next.js

This library is designed for the Node.js ecosystem. While it works perfectly in Next.js Server Components and API Routes, it is not recommended for Client Components as browsers cannot access environment variables from process.env directly (unless prefixed with NEXT_PUBLIC_ which is handled by Next.js).

Express / NestJS / Node.js

Next.js Server Side

Next.js Client Components

Ready to secure your config?

npm install env-typed-guard