🛡️ env-guard

🤖 AI-Crafted in a Day: This entire package was vibe-coded in 1 day using MiniMax M2 LLM and GROK Code Fast 1. Zero human-written code - just pure AI creativity unleashed!

Schema-based validator for environment variables with TypeScript support

env-guard is a zero-dependency, enterprise-grade validation library for Node.js environment variables. It provides type safety, runtime validation, automatic .env.example generation, and comprehensive error reporting.

✨ Features

• 🔒 Type Safety: Full TypeScript support with type inference
• ⚡ Zero Dependencies: Lightweight with no external dependencies
• 🎯 Schema-Based: Define once, validate anywhere
• 🔄 Type Coercion: Automatic string → number/boolean conversion
• ✅ Built-in Validators: URL, port, email, IP, JSON, regex validation
• 🌍 Environment Context: Different rules for dev/staging/production
• 📝 Auto-Generation: Generate .env.example files automatically
• 🛠️ CLI Tool: Command-line interface for validation and generation
• 💪 Enterprise Ready: 94.16% test coverage, comprehensive error handling

🎯 Why Choose env-guard?

⚡ Zero Dependencies

Lightweight, fast, and secure. Your project stays lean. No need to install or learn heavy schema libraries like Zod.

🛠️ Powerful & Expressive Schema

Define complex rules with a simple, intuitive JavaScript object. You don't just check for a string; you validate the format and type with built-in special types.

// A simple object is all you need:
const schema = defineSchema({
  PORT: { type: 'port', default: 3000 },
  API_URL: { type: 'url', required: true },
  _environments: {
    production: { API_URL: { required: true } }
  }
});

🔄 Complete CLI Workflow

A fully integrated toolchain that ensures consistency from development to production. Go from schema definition to .env.example generation to CI validation with a single, reliable tool.

🏢 Enterprise-Ready

Built-in support for environment-specific rules makes managing complex deployments for development, staging, and production trivial.

📊 How env-guard is Different

| Feature | env-guard (Your Library) | Zod-based Validators | .env.example Validators | |---------|---------------------------|---------------------|------------------------| | Dependencies | Zero | Requires Zod | Often none | | Schema | Powerful JS Object | Zod Schema (external) | Limited (file-based) | | Built-in Types | port, url, ip, email | string, number, etc. | No types, just keys | | CLI Toolchain | ✅ Yes (Generate, Validate, Check) | Usually none | Usually none | | Learning Curve | Minimal (Just JS objects) | Moderate (Learn Zod) | Minimal |

🚀 Quick Start

Installation

npm install @miit-daga/env-guard
# or
yarn add @miit-daga/env-guard

Basic Usage

const { defineSchema, validateEnv } = require('@miit-daga/env-guard');

// Define your schema
const schema = defineSchema({
  PORT: {
    type: 'port',
    required: true,
    default: 3000,
    description: 'Server port number'
  },
  NODE_ENV: {
    type: 'string',
    enum: ['development', 'production', 'test'],
    default: 'development'
  },
  DEBUG: {
    type: 'boolean',
    default: false
  }
});

// Validate environment variables
const result = validateEnv(schema, process.env);

if (result.success) {
  console.log('✅ Validation successful!');
  console.log('PORT:', result.data.PORT);
  console.log('NODE_ENV:', result.data.NODE_ENV);
} else {
  console.log('❌ Validation failed:');
  result.errors.forEach(error => {
    console.log(`- ${error.field}: ${error.message}`);
  });
}

📋 API Reference

Core Functions

defineSchema(schema)

Compiles a schema definition into a validated schema object.

const compiledSchema = defineSchema({
  DATABASE_URL: {
    type: 'url',
    required: true,
    description: 'Database connection string'
  },
  API_KEY: {
    type: 'string',
    required: true,
    minLength: 32
  }
});

validateEnv(schema, envVars, environment)

Validates environment variables against a compiled schema.

const result = validateEnv(schema, process.env, 'production');
// Returns: { success: boolean, data?: object, errors: array, hasErrors: boolean }

Schema Options

Each field in your schema can have the following options:

| Option | Type | Description | |--------|------|-------------| | type | string | Required. Field type: 'string', 'number', 'boolean', 'url', 'port', 'email', 'ip', 'json', 'regex' | | required | boolean | Whether the field must be present (default: false) | | default | any | Default value if not provided (can be a function) | | description | string | Field description for documentation | | enum | array | Array of allowed values | | validate | function | Custom validation function | | transform | function | Transform function applied after coercion | | minLength | number | Minimum string length (string type only) | | maxLength | number | Maximum string length (string type only) | | min | number | Minimum numeric value (number type only) | | max | number | Maximum numeric value (number type only) | | protocols | array | Allowed URL protocols (url type only) | | version | string | IP version: 'ipv4', 'ipv6', 'any' (ip type only) | | pattern | RegExp | Regex pattern (regex type only) |

Type Coercion

env-guard automatically coerces string values to their target types:

// String values are trimmed
'  hello  ' → 'hello'

// Number coercion with validation
'8080' → 8080
'abc' → ValidationError

// Boolean coercion
'true' → true
'1' → true
'false' → false
'0' → false
'maybe' → ValidationError

Built-in Validators

URL Validator

validators.url('https://example.com'); // ✅ true
validators.url('http://localhost:3000'); // ✅ true
validators.url('invalid-url'); // ❌ 'Invalid URL format'

Port Validator

validators.port(3000); // ✅ true
validators.port(65536); // ❌ 'Port must be between 1 and 65535'

Email Validator

validators.email('[email protected]'); // ✅ true
validators.email('invalid-email'); // ❌ 'Invalid email format'

IP Validator

validators.ip('192.168.1.1'); // ✅ true
validators.ip('::1'); // ✅ true (IPv6)
validators.ip('invalid-ip'); // ❌ 'Invalid IP address format'

JSON Validator

validators.json('{"key": "value"}'); // ✅ true
validators.json('invalid-json'); // ❌ 'Invalid JSON format'

🛠️ CLI Tool

env-guard includes a powerful CLI for validation and .env.example generation.

Installation

npm install -g @miit-daga/env-guard

Commands

Validate Environment

env-guard validate --schema schema.js
env-guard validate --schema schema.js --env-file .env.local
env-guard validate --schema schema.js --format json

Generate .env.example

env-guard generate --schema schema.js
env-guard generate --schema schema.js --output my-env.example --include-comments

Check Schema

env-guard check --schema schema.js
env-guard check --schema schema.js --detailed

🌟 Advanced Features

Custom Validators

const schema = defineSchema({
  API_KEY: {
    type: 'string',
    required: true,
    validate: (value) => {
      if (!value.startsWith('sk-')) {
        return 'API key must start with "sk-"';
      }
      return true;
    }
  }
});

Transforms

const schema = defineSchema({
  DATABASE_URL: {
    type: 'string',
    transform: (url) => {
      return url.replace('localhost', '127.0.0.1');
    }
  }
});

Environment-Specific Rules

const schema = {
  API_URL: {
    type: 'url',
    required: false,
    description: 'API base URL'
  },
  _environments: {
    production: {
      API_URL: {
        required: true
      }
    }
  }
};

const result = validateEnv(defineSchema(schema), env, 'production');
// API_URL becomes required in production environment

🏗️ Framework Integration

Express.js

// app.js
const express = require('express');
const { defineSchema, validateEnv } = require('@miit-daga/env-guard');

const app = express();

// Define schema
const schema = defineSchema({
  PORT: { type: 'port', required: true, default: 3000 },
  DATABASE_URL: { type: 'url', required: true },
  JWT_SECRET: { type: 'string', required: true, minLength: 32 }
});

// Validate and configure
const result = validateEnv(schema, process.env);
if (!result.success) {
  console.error('Environment validation failed:', result.errors);
  process.exit(1);
}

app.set('port', result.data.PORT);
app.set('env', result.data.NODE_ENV);

### Next.js
```javascript
// next.config.js
const { defineSchema, validateEnv } = require('@miit-daga/env-guard');

const schema = defineSchema({
  DATABASE_URL: { type: 'url', required: true },
  NEXT_PUBLIC_API_URL: { type: 'url', required: true }
});

const envValidation = validateEnv(schema, process.env);
if (!envValidation.success) {
  console.error('❌ Environment validation failed:');
  envValidation.errors.forEach(error => {
    console.error(`  ${error.field}: ${error.message}`);
  });
  process.exit(1);
}

module.exports = {
  env: {
    DATABASE_URL: envValidation.data.DATABASE_URL,
    NEXT_PUBLIC_API_URL: envValidation.data.NEXT_PUBLIC_API_URL
  }
};

📝 Example Files

See the examples/ directory for complete integration examples:

• basic-usage.js - Basic usage examples
• express-integration.js - Express.js integration
• nextjs-integration.js - Next.js integration
• nestjs-integration.js - NestJS integration

🐛 Error Handling

env-guard provides detailed, actionable error messages:

const result = validateEnv(schema, {
  PORT: 'not-a-port',
  API_KEY: 'abc'
});

console.log(result.errors);
// [
//   {
//     field: 'PORT',
//     message: 'Port must be an integer between 1 and 65535',
//     value: 'not-a-port',
//     expected: 'valid port number',
//     received: 'string',
//     type: 'FormatError'
//   },
//   {
//     field: 'API_KEY',
//     message: 'String must be at least 32 characters long',
//     value: 'abc',
//     expected: 'min 32 chars',
//     received: '3 chars',
//     type: 'FormatError'
//   }
// ]

🔧 Development

# Install dependencies
npm install

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Build TypeScript
npm run build

# Run CLI
node bin/env-guard.js validate --schema schema.js

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Add tests for any new functionality
5. Run the test suite: npm test
6. Submit a pull request

Development Guidelines

• Follow the existing code style (ESLint + Prettier)
• Add tests for new features and bug fixes
• Update documentation for API changes
• Ensure all tests pass before submitting

🆘 Support

Need help? Here are your options:

📖 Documentation

• API Reference
• CLI Documentation
• Quick Start Guide
• Troubleshooting

🐛 Issues

Found a bug? Open an issue on GitHub.

💬 Discussions

Have questions or ideas? Start a discussion on GitHub.

👤 Author

Miit Daga

💼 LinkedIn
🌐 Website

📊 Test Coverage

• 116 tests passing (100% success rate)
• 94.16% code coverage
• Zero dependencies
• TypeScript strict mode

Built with ❤️ for the Node.js community