dev-env-toolkit

Type-safe environment variables for Node.js and TypeScript

A zero-dependency, TypeScript-first toolkit for managing environment variables with full type inference, validation, and helpful error messages.

Features

• Type-Safe: Full TypeScript support with automatic type inference
• Zero Dependencies: No external runtime dependencies
• Chainable API: Intuitive Zod-like schema definition
• Validation: Built-in validators for strings, numbers, booleans, enums, and arrays
• Helpful Errors: Clear error messages showing exactly what went wrong
• .env Support: Built-in parser for .env files

Installation

npm install dev-env-toolkit

Quick Start

import { env } from 'dev-env-toolkit';

// Define your environment schema
const config = env.create({
  PORT: env.number().default(3000),
  DATABASE_URL: env.string().url(),
  NODE_ENV: env.enum(['development', 'production', 'test'] as const),
  DEBUG: env.boolean().default(false),
  API_KEYS: env.array().separator(','),
});

// Fully typed! TypeScript knows the exact types
console.log(config.PORT);        // number
console.log(config.DATABASE_URL); // string
console.log(config.NODE_ENV);     // 'development' | 'production' | 'test'
console.log(config.DEBUG);        // boolean
console.log(config.API_KEYS);     // string[]

Validators

String

env.string()                    // Required string
env.string().optional()         // Optional string
env.string().default('value')   // With default value
env.string().min(5)             // Minimum length
env.string().max(100)           // Maximum length
env.string().url()              // Valid URL format
env.string().email()            // Valid email format
env.string().regex(/^[A-Z]+$/)  // Custom regex pattern

Number

env.number()                    // Required number
env.number().optional()         // Optional number
env.number().default(3000)      // With default value
env.number().min(1)             // Minimum value
env.number().max(65535)         // Maximum value
env.number().int()              // Must be integer
env.number().positive()         // Must be positive
env.number().port()             // Valid port (1-65535, integer)

Boolean

Accepts: true, false, 1, 0, yes, no, on, off (case-insensitive)

env.boolean()                   // Required boolean
env.boolean().optional()        // Optional boolean
env.boolean().default(false)    // With default value

Enum

env.enum(['development', 'production', 'test'] as const)
env.enum(['small', 'medium', 'large'] as const).default('medium')

Array

env.array()                     // Comma-separated by default
env.array().separator('|')      // Custom separator
env.array().min(1)              // Minimum items
env.array().max(10)             // Maximum items
env.array().default(['a', 'b']) // Default value

Loading .env Files

import { env } from 'dev-env-toolkit';

// Load from .env file before parsing
const config = env.create({
  DATABASE_URL: env.string(),
}, { path: '.env' });

// Or load manually
env.load('.env');
env.load('.env.local', { override: true }); // Override existing values

Safe Parsing

Use safeParse to handle validation errors without throwing:

import { env } from 'dev-env-toolkit';

const result = env.safeParse({
  PORT: env.number(),
  DATABASE_URL: env.string(),
});

if (result.success) {
  console.log(result.data.PORT);
} else {
  console.error('Validation failed:', result.errors);
  // result.errors: [{ key: 'DATABASE_URL', message: '...' }]
}

Error Messages

When validation fails, you get clear, actionable error messages:

Environment Validation Failed

Found 2 errors:

  DATABASE_URL: Required environment variable is missing

  PORT: Invalid number format
    Received: not-a-number

Tip: Check your .env file or environment variables

TypeScript Integration

The library provides full type inference:

import { env, type InferEnv } from 'dev-env-toolkit';

const schema = {
  PORT: env.number().default(3000),
  DEBUG: env.boolean().optional(),
  NODE_ENV: env.enum(['development', 'production'] as const),
};

// Extract the type
type Config = InferEnv<typeof schema>;
// { PORT: number; DEBUG: boolean | undefined; NODE_ENV: 'development' | 'production' }

const config = env.create(schema);

API Reference

env.create(schema, options?)

Create a type-safe configuration object from environment variables.

Options:

• path?: string - Path to .env file to load
• throwOnError?: boolean - Whether to throw on validation errors (default: true)
• env?: Record<string, string> - Custom environment object (default: process.env)

env.safeParse(schema, options?)

Parse environment variables without throwing. Returns a result object.

env.load(path, options?)

Load environment variables from a .env file into process.env.

Options:

• override?: boolean - Whether to override existing values (default: false)

env.parse(path)

Parse a .env file and return the key-value pairs without modifying process.env.

License

MIT