Status: Experimental

validatenv is a typesafe library for validating environment variables.

🌟 Motivation

Create a type-safe, straightforward, and lightweight library for validating environment variables using existing validation libraries like Valibot or Zod. Additionally, I didn't trust existing libraries, as reading environment variables is a particularly vulnerable task.

⚖️ Alternatives

• envalid

📖 Usage

import {
	devDefault,
	numberMiddleware,
	portValidator,
	validateEnv,
	validateEnvVar
} from 'validatenv';
import { zValidator } from 'validation-adapters/zod';
import * as z from 'zod';
// Load environment variables
import 'dotenv/config';

// Validate multiple environment variables
const env = validateEnv(process.env, {
	// Built-in validator
	port: {
		envKey: 'SERVER_PORT', // Read from SERVER_PORT instead of port
		validator: portValidator,
		defaultValue: devDefault(3000) // Uses default only in development environment
	},

	// Zod validator with middleware
	MAX_CONNECTIONS: {
		validator: zValidator(z.number().min(1).max(100)),
		middlewares: [numberMiddleware], // Converts string input to number
		defaultValue: 10
	},

	// Static value
	NODE_ENV: 'development'
});

// Validate single environment variable
const apiKey = validateEnvVar(
	'API_KEY',
	{
		validator: zValidator(z.string().min(10)),
		description: 'API authentication key', // Shown in validation error messages for better debugging
		example: 'abc123xyz789' // Provides usage example in error messages
	},
	process.env
);

// Type-safe access
console.log(env.port); // number
console.log(env.MAX_CONNECTIONS); // number
console.log(apiKey); // string