Environment Configuration Validator

Validate .env files across local, staging, and production environments. Ensure all required secrets, database URLs, API keys, and public variables are properly scoped, set, and secure.

Core Capabilities

1. Validate Environment Files

To validate environment configuration:

• Parse .env , .env.local , .env.production , etc.

• Check for required variables

• Verify variable naming conventions

• Detect security issues (exposed secrets, weak values)

• Use scripts/validate_env.py for automated validation

2. Check Variable Scoping

Ensure proper scoping of environment variables:

• Public variables (NEXT_PUBLIC_* ): Accessible in browser

• Private variables: Server-side only

• Database credentials: Never exposed to client

• API keys: Properly scoped based on usage

3. Cross-Environment Validation

Compare configurations across environments:

• Identify missing variables in staging/production

• Check for environment-specific overrides

• Ensure consistency in variable names

• Validate environment-specific values (URLs, keys)

4. Security Auditing

Detect security vulnerabilities in environment configuration:

• Exposed secrets in public variables

• Weak or default values

• Hardcoded credentials in code

• Missing required security variables (JWT secrets, encryption keys)

Validation Rules

Required Variables

Ensure these categories of variables are present:

Database Connection

• DATABASE_URL or equivalent

• Connection pool settings (optional)

Authentication

• JWT_SECRET or AUTH_SECRET

• OAuth credentials (if using OAuth)

• Session secrets

External APIs

• Third-party API keys

• Service endpoints

• Rate limiting tokens

Application Config

• NODE_ENV

• NEXT_PUBLIC_APP_URL or APP_URL

• Feature flags (optional)

Email/Notifications (if used)

• SMTP credentials

• Email service API keys

Naming Conventions

Follow Next.js environment variable conventions:

Public variables: NEXT_PUBLIC_* prefix

• Example: NEXT_PUBLIC_API_URL

• Accessible in browser

• Never put secrets here

Private variables: No prefix

• Example: DATABASE_URL , API_SECRET

• Server-side only

• Safe for secrets

Naming style: SCREAMING_SNAKE_CASE

• Example: DATABASE_URL , JWT_SECRET , STRIPE_API_KEY

Security Rules

Never expose secrets in public variables

• [ERROR] NEXT_PUBLIC_DATABASE_URL

• [OK] DATABASE_URL

Database URLs must be private

• [ERROR] NEXT_PUBLIC_DB_URL

• [OK] DATABASE_URL

API keys scoping

• Client-side API keys → NEXT_PUBLIC_* (e.g., Google Maps)

• Server-side API keys → No prefix (e.g., Stripe secret)

No hardcoded secrets in code

• Use environment variables for all secrets

• Never commit .env.local or .env.production

Strong secrets

• JWT/session secrets: minimum 32 characters

• Use cryptographically random values

• No default or example values in production

Validation Script

Use scripts/validate_env.py to automate validation:

Validate current .env file

python scripts/validate_env.py

Validate specific file

python scripts/validate_env.py --file .env.production

Compare multiple environments

python scripts/validate_env.py --compare .env.local .env.production

Check against required variables template

python scripts/validate_env.py --template .env.example

The script checks:

• Required variables are present

• Naming conventions are followed

• No secrets in public variables

• No weak or default values

• Consistent naming across environments

Common Issues and Solutions

Issue: Missing DATABASE_URL in Production

Detection: Script reports missing required variable

Solution:

Add to .env.production

DATABASE_URL="postgresql://user:password@host:5432/dbname"

Note: Use different databases for dev/staging/prod

Issue: Secret Exposed in Public Variable

Detection: Script finds NEXT_PUBLIC_ prefix on secret

Problem:

[ERROR] WRONG - secret exposed to browser

NEXT_PUBLIC_API_SECRET="secret123"

Solution:

[OK] CORRECT - server-side only

API_SECRET="secret123"

Issue: Weak JWT Secret

Detection: Script detects short or weak secret

Problem:

[ERROR] WRONG - too short, predictable

JWT_SECRET="secret"

Solution:

[OK] CORRECT - strong, random, 32+ characters

JWT_SECRET="a8f3d9c2e1b7f4a6d8c3e9b2f1a7d4c8e3b9f2a1d7c4e8b3f9a2d1c7e4b8f3a9"

Generate with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Issue: Inconsistent Variable Names Across Environments

Detection: Script comparison shows name mismatch

Problem:

.env.local

DATABASE_URL="..."

.env.production

DB_URL="..." # [ERROR] Different name

Solution: Use consistent names

Both files

DATABASE_URL="..."

Issue: Missing Public API URL

Detection: Client-side code fails to connect to API

Problem: NEXT_PUBLIC_API_URL not set

Solution:

.env.local

NEXT_PUBLIC_API_URL="http://localhost:3000"

.env.production

NEXT_PUBLIC_API_URL="https://api.yourapp.com"

Resource Files

scripts/validate_env.py

Python script to validate environment files, check for security issues, compare across environments, and verify against templates. Provides detailed error messages and suggestions.

references/env_best_practices.md

Comprehensive guide to environment variable management including:

• Security best practices

• Naming conventions

• Scoping rules (public vs private)

• Common patterns for different services

• Environment-specific configuration

• Secret rotation strategies

assets/.env.example

Template showing all required environment variables for a worldbuilding application. Use as a reference for setting up new environments or auditing existing ones.

Environment-Specific Configuration

Development (.env.local)

Database

DATABASE_URL="postgresql://user:password@localhost:5432/worldbuilding_dev"

Authentication

JWT_SECRET="dev-secret-change-in-production" NEXTAUTH_URL="http://localhost:3000" NEXTAUTH_SECRET="dev-nextauth-secret"

Public

NEXT_PUBLIC_API_URL="http://localhost:3000" NEXT_PUBLIC_APP_NAME="Worldbuilding App (Dev)"

External APIs (test keys)

OPENAI_API_KEY="sk-test-..." STRIPE_SECRET_KEY="sk_test_..."

Staging (.env.staging)

Database

DATABASE_URL="postgresql://user:password@staging-db.com:5432/worldbuilding_staging"

Authentication

JWT_SECRET="staging-secret-32-chars-minimum" NEXTAUTH_URL="https://staging.yourapp.com" NEXTAUTH_SECRET="staging-nextauth-secret"

Public

NEXT_PUBLIC_API_URL="https://staging.yourapp.com" NEXT_PUBLIC_APP_NAME="Worldbuilding App (Staging)"

External APIs (test keys)

OPENAI_API_KEY="sk-test-..." STRIPE_SECRET_KEY="sk_test_..."

Production (.env.production)

Database

DATABASE_URL="postgresql://user:password@prod-db.com:5432/worldbuilding_prod"

Authentication

JWT_SECRET="production-secret-use-crypto-random-32-chars-minimum" NEXTAUTH_URL="https://yourapp.com" NEXTAUTH_SECRET="production-nextauth-secret"

Public

NEXT_PUBLIC_API_URL="https://api.yourapp.com" NEXT_PUBLIC_APP_NAME="Worldbuilding App"

External APIs (production keys)

OPENAI_API_KEY="sk-live-..." STRIPE_SECRET_KEY="sk_live_..."

Monitoring

SENTRY_DSN="https://..."

Best Practices

Never commit secrets

• Add .env.local , .env.production to .gitignore

• Commit .env.example as a template

Use strong, random secrets

• Minimum 32 characters for JWT/session secrets

• Use crypto.randomBytes() or password manager

Scope variables correctly

• Public (NEXT_PUBLIC_* ): Only non-sensitive, client-accessible data

• Private (no prefix): All secrets, credentials, server-only config

Consistent naming

• Use same variable names across all environments

• Follow SCREAMING_SNAKE_CASE convention

Environment-specific values

• Different database URLs per environment

• Test API keys in dev/staging, production keys in prod

• Environment-specific URLs and endpoints

Document required variables

• Keep .env.example updated

• Add comments explaining each variable

• Document where to get values (API dashboard, etc.)

Validate on deployment

• Run validation script in CI/CD pipeline

• Fail deployment if required variables missing

• Check for security issues before deploying

Rotate secrets regularly

• Change JWT secrets periodically

• Rotate API keys on schedule

• Update after team member departures

Use secret management tools

• Consider Vercel Environment Variables

• AWS Secrets Manager, HashiCorp Vault for sensitive data

• Never store production secrets in code or comments

Test environment parity

• Staging should mirror production as closely as possible

• Use same variable names, just different values

• Test with production-like data

Integration with Worldbuilding App

Common environment variables for worldbuilding applications:

Database

DATABASE_URL="postgresql://..." DATABASE_POOL_SIZE="10" # Optional

Authentication

JWT_SECRET="..." NEXTAUTH_URL="..." NEXTAUTH_SECRET="..."

External APIs

AI services (optional)

OPENAI_API_KEY="..."

Maps (if using)

NEXT_PUBLIC_GOOGLE_MAPS_API_KEY="..."

Image hosting (if using)

CLOUDINARY_URL="..."

Application

NODE_ENV="production" NEXT_PUBLIC_APP_URL="https://..." NEXT_PUBLIC_APP_NAME="Worldbuilding App"

Email (if using)

SMTP_HOST="..." SMTP_PORT="587" SMTP_USER="..." SMTP_PASSWORD="..."

Consult references/env_best_practices.md for detailed guidance and assets/.env.example for a complete template.