Envado

Envado is a lightweight and type-safe library for parsing and validating environment variables in both Node.js and browser environments. It provides a minimal yet powerful API, ensuring expressiveness without bloating your project.

Features

• Type-safe: Full TypeScript support with automatic type inference
• Rich Validation: Extensive built-in validators for common use cases
• Customizable: Extend functionality with your own validators and transformers
• Environment Detection: Built-in environment type helpers
• Lightweight: Zero dependencies (except for optional dotenv integration)
• Browser-Compatible: Works seamlessly with bundlers like Vite, Webpack, and others
• Intelligent Defaults: Sensible defaults that handle most common use cases

Installation

npm install envado

Quick Start

import { validateEnv } from "envado";

const env = validateEnv(({ string, number, array }) => ({
  PORT: number({ default: 3000 }),
  API_KEY: string(),
  ALLOWED_ORIGINS: array<string>(),
  NODE_ENV: string(),
}));

// TypeScript-safe access
console.log(env.PORT); // number
console.log(env.API_KEY); // string

Validators and Modifiers

| Validator | Methods | Description | |--------------|-------------------------------------------|--------------------------------------------| | string() | .oneOf(['a', 'b']) .url() .email() .min(length) .max(length) | String validation with various constraints | | number() | .min(value) .max(value) .port() | Number validation with range constraints | | boolean() | | Converts truthy/falsy strings to booleans | | array() | .min(length) .max(length) .items(schema) .withSeparator(separator) | Auto-parses comma-separated strings to arrays | | object() | .strict() | Validates nested object structures |

Common Modifiers

All validators support these modifiers:

.optional()                        // Make field optional
.custom(value => string|undefined) // Custom validation
.transform(value => newValue)      // Custom transformation

Environment Detection

Envado makes it easy to determine the current environment:

if (env.isDev) {
  console.log("Running in development mode");
}

Available properties:

| Property | Description | |----------|-------------| | env.isDev | NODE_ENV === 'development' | | env.isProd | NODE_ENV === 'production' | | env.isTest | NODE_ENV === 'test' | | env.isStaging | NODE_ENV === 'staging' | | env.isLocal | NODE_ENV === 'local' | | env.environment | Raw NODE_ENV value |

Browser Support (Vite, Webpack, etc.)

Envado works seamlessly with browser bundlers like Vite and Webpack:

import { validateEnv } from "envado";

// For Vite
const env = validateEnv(schema, {
  envVars: import.meta.env,
  prefix: "VITE_"
});

// Access as usual
console.log(env.API_URL);

Advanced Configuration

Envado allows custom .env file paths and overriding variables:

validateEnv(schema, {
  // Specify custom .env files (Node.js only)
  path: [".env", ".env.test"],
  
  // Override `process.env` values
  envVars: import.meta.env,
  
  // Specify a prefix for env variables (e.g., VITE_)
  prefix: "VITE_",
});

Error Handling

try {
  const env = validateEnv((builder) => ({
    PORT: builder.number().port(),
  }));
} catch (error) {
  // Detailed validation errors:
  // "Environment validation failed:
  // PORT: Invalid port number"
}

Validation Table

| Validator | Method | Description | Example | |-----------|--------|-------------|---------| | string() | .oneOf(['a', 'b']) | Validates string is one of provided values | string().oneOf(['dev', 'prod']) | | | .url() | Validates string is a valid URL | string().url() | | | .email() | Validates string is a valid email | string().email() | | | .min(length) | Validates minimum string length | string().min(8) | | | .max(length) | Validates maximum string length | string().max(100) | | number() | .min(value) | Validates minimum value | number().min(1) | | | .max(value) | Validates maximum value | number().max(65535) | | | .port() | Validates is a valid port number (1-65535) | number().port() | | boolean() | | Converts strings to booleans | boolean({ default: false }) | | array() | .min(length) | Validates minimum array length | array().min(1) | | | .max(length) | Validates maximum array length | array().max(10) | | | .items(schema) | Validates each array item | array().items(number().min(0)) | | | .withSeparator(sep) | Sets custom separator | array().withSeparator('|') | | object() | .strict() | Disallows extra properties | object(schema).strict() |

Advanced Example

const env = validateEnv((builder) => ({
  // Database config
  DB_HOST: builder.string(),
  DB_PORT: builder.number().port(),
  DB_USER: builder.string(),
  DB_PASS: builder.string(),
  
  // Email configuration
  SMTP_SERVER: builder.string(),
  SMTP_PORT: builder.number().port(),
  ADMIN_EMAIL: builder.string().email(),
  
  // API configuration
  API_KEYS: builder
    .array<string>()
    .min(1),
    
  // Feature flags
  FEATURES: builder
    .object({
      enableCache: builder.boolean(),
      maxUsers: builder.number().min(1),
    })
    .strict(),
}));

Custom Validation Example

const env = validateEnv((builder) => ({
  // Define a custom validator for API keys
  API_KEY: builder.string().custom(value => {
    const regex = /^[A-Z0-9]{32}$/;
    return regex.test(value) ? undefined : 'API key must be 32 uppercase alphanumeric characters';
  }),
  
  // Custom transformation
  DATABASE_URL: builder.string().transform(url => {
    // Add SSL parameters if not present
    if (!url.includes('sslmode=')) {
      return `${url}?sslmode=require`;
    }
    return url;
  }),
}));

Working with Multiple Environments

// .env.development
const devEnv = validateEnv(schema, { path: '.env.development' });

// .env.production
const prodEnv = validateEnv(schema, { path: '.env.production' });

// Dynamic based on NODE_ENV
const env = validateEnv(schema, { 
  path: `.env.${process.env.NODE_ENV || 'development'}` 
});

License

MIT