env-shield

TypeScript-first environment variable validation with full type inference. Zero dependencies.

Install

npm install env-shield

Usage

import { createEnv, s } from 'env-shield'

const env = createEnv({
  schema: {
    DATABASE_URL: s.url(),
    PORT: s.port().default(3000),
    NODE_ENV: s.enum('development', 'staging', 'production'),
    DEBUG: s.boolean().default(false),
    API_KEY: s.string().min(10),
    MAX_RETRIES: s.number().int().min(0).max(10).default(3),
    ADMIN_EMAIL: s.email().optional(),
  },
})

// Full type inference - no manual typing needed
env.DATABASE_URL  // string
env.PORT          // number
env.NODE_ENV      // 'development' | 'staging' | 'production'
env.DEBUG         // boolean
env.API_KEY       // string
env.MAX_RETRIES   // number
env.ADMIN_EMAIL   // string | undefined

Schema Types

| Builder | Output Type | Description | |---------|------------|-------------| | s.string() | string | Basic string variable | | s.number() | number | Parsed number | | s.boolean() | boolean | Accepts true/false/1/0/yes/no/on/off | | s.port() | number | Integer between 1-65535 | | s.url() | string | Validated URL format | | s.email() | string | Validated email format | | s.enum('a', 'b') | 'a' \| 'b' | One of the specified values | | s.json<T>() | T | Parsed JSON string |

Modifiers

s.string().optional()      // can be missing (type includes undefined)
s.string().default('val')  // fallback value (type excludes undefined)
s.string().min(5)          // min length (or min value for numbers)
s.string().max(100)        // max length (or max value for numbers)
s.string().regex(/pattern/) // regex validation
s.string().url()           // URL format validation
s.string().email()         // email format validation
s.number().int()           // integer validation
s.string().describe('...')  // description for documentation

Error Output

When validation fails, env-shield throws an EnvValidationError with all failures:

env-shield: 3 environment variables failed validation:

  ✗ DATABASE_URL: Required variable is missing
  ✗ PORT: Expected a number, got "abc" (received: "abc")
  ✗ NODE_ENV: Must be one of: development, staging, production (received: "test")

Custom Source

const env = createEnv({
  schema: { ... },
  source: myEnvObject,  // defaults to process.env
})

License

MIT