envguard

TypeScript-first environment variable validation with runtime safety and static inference.

Installation

npm install @prerak20/envguard

Why envguard?

• Runtime validation for production safety
• Strong static type inference from schema definitions
• Chainable builder API focused on environment variables
• Helpful error output (expected, actual, reason)
• .env.example generation from the same schema
• ESM + CJS package output
• Zero external runtime dependencies

Example

import { boolean, defineEnv, enumType, number, string } from "@prerak20/envguard";

const env = defineEnv({
  PORT: number().min(1000).max(9999).default(3000),
  NODE_ENV: enumType(["development", "production"]),
  DATABASE_URL: string().url(),
  ENABLE_LOGS: boolean().default(false)
});

// env.PORT -> number
// env.NODE_ENV -> "development" | "production"
// env.DATABASE_URL -> string
// env.ENABLE_LOGS -> boolean

Comparison vs zod

envguard is intentionally narrower than zod:

• Optimized for environment variable workflows
• Smaller API surface for env parsing tasks
• Built-in .env.example generation
• No runtime dependencies

Use zod when you need broad JSON/object/domain validation across app boundaries. Use envguard when env validation is the primary concern.

API Docs

defineEnv(schema, source?)

• schema: object mapping env keys to schema builders
• source (optional): custom object, defaults to process.env
• returns parsed + validated object with inferred TypeScript types
• throws EnvValidationError when validation fails

string()

• .min(length)
• .max(length)
• .regex(pattern)
• .url()
• .optional()
• .default(value)

number()

• .min(value)
• .max(value)
• .integer()
• .optional()
• .default(value)

boolean()

• .optional()
• .default(value)

enumType(values)

• accepts a non-empty tuple/list of strings
• output type is inferred as a union of those string literals
• .optional()
• .default(value)

generateExample(schema)

Returns a formatted .env.example string from the provided schema.

Examples

Custom source object

import { defineEnv, number } from "@prerak20/envguard";

const env = defineEnv(
  {
    PORT: number().default(3000)
  },
  {
    PORT: "8080"
  }
);

Error output

envguard validation failed:
1. PORT
   expected: number >= 1000
   actual: 500
   reason: number is below minimum

Generate .env.example

import { boolean, enumType, generateExample, number, string } from "@prerak20/envguard";

const example = generateExample({
  PORT: number().default(3000),
  NODE_ENV: enumType(["development", "production"]),
  DATABASE_URL: string().url(),
  ENABLE_LOGS: boolean().default(false)
});