Configuration Validator

Validates configuration files and environment variables to prevent runtime errors and missing settings.

When to Use

•Working with environment variables or config files
•Deployment or configuration issues
•User mentions ".env", "config", "environment variables", or "settings"

Instructions

1. Find Configuration Files

Search for:

•.env, .env.example, .env.local
•config/, config.js, config.json
•settings.py, application.yml
•appsettings.json, .env.production

2. Detect Missing Variables

Compare .env.example vs .env:

bash

# Variables in example but not in .env
comm -23 <(grep -o '^[A-Z_]*' .env.example | sort) <(grep -o '^[A-Z_]*' .env | sort)

Common required variables:

code

DATABASE_URL
API_KEY
SECRET_KEY
NODE_ENV
PORT

3. Validate Variable Format

Check for common issues:

javascript

// Missing quotes for values with spaces
DATABASE_URL=postgres://localhost/db name  // Bad
DATABASE_URL="postgres://localhost/db name"  // Good

// Missing protocol
API_URL=example.com  // Bad
API_URL=https://example.com  // Good

// Boolean as string
DEBUG=true  // Might be interpreted as string
DEBUG=1  // More explicit

4. Validate Required Variables at Runtime

Node.js example:

javascript

const requiredEnvVars = [
  'DATABASE_URL',
  'API_KEY',
  'JWT_SECRET'
];

const missing = requiredEnvVars.filter(v => !process.env[v]);

if (missing.length > 0) {
  throw new Error(`Missing required env vars: ${missing.join(', ')}`);
}

Python example:

python

import os

REQUIRED_ENV_VARS = [
    'DATABASE_URL',
    'SECRET_KEY',
    'ALLOWED_HOSTS'
]

missing = [var for var in REQUIRED_ENV_VARS if not os.getenv(var)]

if missing:
    raise EnvironmentError(f"Missing env vars: {', '.join(missing)}")

5. Type Validation

Validate types:

javascript

const config = {
  port: parseInt(process.env.PORT || '3000', 10),
  debug: process.env.DEBUG === 'true',
  apiUrl: new URL(process.env.API_URL), // Throws if invalid
  maxConnections: Number(process.env.MAX_CONNECTIONS),
};

// Validate
if (isNaN(config.port) || config.port < 1 || config.port > 65535) {
  throw new Error('PORT must be a valid port number');
}

6. Generate .env.example

Create template from actual .env:

bash

# Remove values, keep keys
sed 's/=.*/=/' .env > .env.example

Or with placeholders:

code

DATABASE_URL=postgres://user:password@localhost:5432/dbname
API_KEY=your_api_key_here
SECRET_KEY=generate_random_secret
PORT=3000
NODE_ENV=development

7. Configuration Schema

Define schema (using Joi example):

javascript

const Joi = require('joi');

const envSchema = Joi.object({
  NODE_ENV: Joi.string()
    .valid('development', 'production', 'test')
    .required(),
  PORT: Joi.number()
    .port()
    .default(3000),
  DATABASE_URL: Joi.string()
    .uri()
    .required(),
  API_KEY: Joi.string()
    .min(32)
    .required(),
  DEBUG: Joi.boolean()
    .default(false),
}).unknown();

const { error, value } = envSchema.validate(process.env);

if (error) {
  throw new Error(`Config validation error: ${error.message}`);
}

module.exports = value;

8. Security Checks

Don't commit secrets:

bash

# Check if .env is gitignored
if ! grep -q "^\.env$" .gitignore; then
  echo "Warning: .env not in .gitignore"
fi

# Check for hardcoded secrets in code
grep -r "api_key.*=.*['\"]" --exclude-dir=node_modules

Common security issues:

•Hardcoded passwords/keys
•Default secrets in production
•Exposed sensitive configs
•Unencrypted secrets

9. Environment-Specific Configs

Organize by environment:

code

.env.development
.env.staging
.env.production
.env.test

Load appropriately:

javascript

require('dotenv').config({
  path: `.env.${process.env.NODE_ENV || 'development'}`
});

10. Document All Variables

Create CONFIG.md:

markdown

# Configuration

## Environment Variables

### Required

- `DATABASE_URL`: PostgreSQL connection string
  - Format: `postgres://user:pass@host:port/db`
  - Example: `postgres://app:secret@localhost:5432/myapp`

- `API_KEY`: Third-party API key
  - Obtain from: https://dashboard.example.com
  - Required scopes: read, write

### Optional

- `PORT`: Server port (default: 3000)
- `DEBUG`: Enable debug logging (default: false)
- `MAX_CONNECTIONS`: Database pool size (default: 10)

## Setup

1. Copy `.env.example` to `.env`
2. Fill in all required values
3. Run `npm run validate-config` to verify

11. Validation Script

Create scripts/validate-config.js:

javascript

const fs = require('fs');

function validateConfig() {
  const required = ['DATABASE_URL', 'API_KEY'];
  const missing = required.filter(v => !process.env[v]);

  if (missing.length > 0) {
    console.error(`❌ Missing: ${missing.join(', ')}`);
    process.exit(1);
  }

  console.log('✓ All required config variables present');
}

validateConfig();

12. Best Practices

•Never commit .env: Always gitignore
•Maintain .env.example: Keep it updated
•Validate on startup: Fail fast if misconfigured
•Use strong defaults: Sensible fallbacks
•Document everything: Explain each variable
•Rotate secrets: Regularly update keys
•Use secret managers: Vault, AWS Secrets Manager for production
•Type check: Validate types, not just presence

Supporting Files

•templates/config-validator.js
•templates/.env.example
•scripts/generate-env-example.sh