project/
├── .env                    # Local development (gitignored)
├── .env.example            # Template (committed)
├── .env.production         # Production overrides (gitignored or in CI)
├── .env.local              # Local overrides (gitignored)
└── src/
    └── lib/
        └── env.ts          # Validation and exports

// lib/env.ts
import { z } from 'zod';

/**
 * Server-side environment variables.
 * These are NOT exposed to the browser.
 */
const serverSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  
  // Database
  DATABASE_URL: z.string().url(),
  
  // External services
  API_URL: z.string().url().default('http://localhost:8787'),
  REDIS_URL: z.string().url().optional(),
  
  // Feature flags
  ENABLE_ANALYTICS: z.coerce.boolean().default(false),
  ENABLE_RATE_LIMITING: z.coerce.boolean().default(true),
  
  // Secrets
  JWT_SECRET: z.string().min(32),
  
  // Logging
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

/**
 * Client-side environment variables.
 * MUST be prefixed with NEXT_PUBLIC_ (Next.js) or VITE_ (Vite)
 */
const clientSchema = z.object({
  NEXT_PUBLIC_API_URL: z.string().url(),
  NEXT_PUBLIC_APP_URL: z.string().url().optional(),
});

// Validate at module load time
const serverEnv = serverSchema.safeParse(process.env);
const clientEnv = clientSchema.safeParse(process.env);

if (!serverEnv.success) {
  console.error('❌ Invalid server environment variables:');
  console.error(JSON.stringify(serverEnv.error.flatten().fieldErrors, null, 2));
  throw new Error('Invalid server environment configuration');
}

if (!clientEnv.success) {
  console.error('❌ Invalid client environment variables:');
  console.error(JSON.stringify(clientEnv.error.flatten().fieldErrors, null, 2));
  throw new Error('Invalid client environment configuration');
}

/**
 * Type-safe server environment.
 * Use this in API routes and server components.
 */
export const env = serverEnv.data;

/**
 * Type-safe client environment.
 * Use this in client components.
 */
export const publicEnv = clientEnv.data;

// Type exports
export type Env = z.infer<typeof serverSchema>;
export type PublicEnv = z.infer<typeof clientSchema>;

// lib/env.ts - No external dependencies

function requireEnv(key: string): string {
  const value = process.env[key];
  if (!value) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
  return value;
}

function optionalEnv(key: string, defaultValue: string): string {
  return process.env[key] || defaultValue;
}

function boolEnv(key: string, defaultValue: boolean): boolean {
  const value = process.env[key];
  if (value === undefined) return defaultValue;
  return value === 'true' || value === '1';
}

function intEnv(key: string, defaultValue: number): number {
  const value = process.env[key];
  if (value === undefined) return defaultValue;
  const parsed = parseInt(value, 10);
  if (isNaN(parsed)) {
    throw new Error(`Environment variable ${key} must be a number`);
  }
  return parsed;
}

export const env = {
  // Required
  DATABASE_URL: requireEnv('DATABASE_URL'),
  JWT_SECRET: requireEnv('JWT_SECRET'),
  
  // Optional with defaults
  API_URL: optionalEnv('API_URL', 'http://localhost:8787'),
  LOG_LEVEL: optionalEnv('LOG_LEVEL', 'info'),
  PORT: intEnv('PORT', 3000),
  
  // Booleans
  ENABLE_ANALYTICS: boolEnv('ENABLE_ANALYTICS', false),
  ENABLE_RATE_LIMITING: boolEnv('ENABLE_RATE_LIMITING', true),
  
  // Computed
  isDev: process.env.NODE_ENV === 'development',
  isProd: process.env.NODE_ENV === 'production',
  isTest: process.env.NODE_ENV === 'test',
} as const;

// Validate on import
Object.keys(env); // Triggers all getters

undefined

# Environment
environment: Literal["development", "production", "test"] = "development"
debug: bool = False

# Database
database_url: str = Field(..., description="PostgreSQL connection string")

# External services
api_url: str = "http://localhost:8787"
redis_url: str | None = None

# Feature flags
enable_analytics: bool = False
enable_rate_limiting: bool = True

# Secrets
jwt_secret: str = Field(..., min_length=32)

# Logging
log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"

@field_validator("database_url")
@classmethod
def validate_database_url(cls, v: str) -> str:
    if not v.startswith(("postgresql://", "postgres://")):
        raise ValueError("database_url must be a PostgreSQL connection string")
    return v

@property
def is_dev(self) -> bool:
    return self.environment == "development"

@property
def is_prod(self) -> bool:
    return self.environment == "production"

class Config:
    env_file = ".env"
    env_file_encoding = "utf-8"
    case_sensitive = False

undefined

undefined

# Required
database_url: str
jwt_secret: str

# Optional
api_url: str
log_level: str
port: int

# Feature flags
enable_analytics: bool
enable_rate_limiting: bool

# Computed
is_dev: bool
is_prod: bool
is_test: bool

undefined

// In API routes
import { env } from '@/lib/env';

export async function GET() {
  if (env.ENABLE_ANALYTICS) {
    await trackEvent('api_call');
  }
  
  const response = await fetch(`${env.API_URL}/data`);
  return Response.json(await response.json());
}

// In client components
import { publicEnv } from '@/lib/env';

const apiClient = createClient(publicEnv.NEXT_PUBLIC_API_URL);

undefined

undefined

undefined

undefined

undefined

undefined

undefined

```yaml

undefined