env-configuration
Apply when managing application configuration: environment variables, secrets management, and config validation.
When & Why to Use This Skill
This Claude skill provides a robust framework for managing application configurations, environment variables, and sensitive secrets. It implements industry-standard practices like the 12-factor app methodology and Zod-based schema validation to ensure application stability and security. By providing clear patterns for file structuring and runtime validation, it helps developers prevent common pitfalls such as hardcoded secrets, missing dependencies, and accidental exposure of sensitive data in client-side code.
Use Cases
- Case 1: Establishing a secure environment variable architecture for Next.js or Node.js projects using .env.local and .env.example templates.
- Case 2: Implementing 'fail-fast' startup logic by validating environment variables against a Zod schema to catch configuration errors before the app runs.
- Case 3: Managing the security boundary between server-side secrets and client-side public variables (e.g., NEXT_PUBLIC_ prefix management).
- Case 4: Standardizing configuration objects across a development team to provide type-safe access to environment settings throughout the codebase.
- Case 5: Auditing and fixing repository security by implementing proper .gitignore rules for environment files and removing hardcoded credentials.
| name | env-configuration |
|---|---|
| description | Apply when managing application configuration: environment variables, secrets management, and config validation. |
| version | 1.0.0 |
| tokens | ~550 |
| confidence | high |
| - https | //nextjs.org/docs/app/building-your-application/configuring/environment-variables |
| last_validated | 2025-01-10 |
| next_review | 2025-01-24 |
| tags | [configuration, environment, security, devops] |
When to Use
Apply when managing application configuration: environment variables, secrets management, and config validation.
Patterns
Pattern 1: Environment File Structure
# Source: https://12factor.net/config
# .env.example (commit this - template without secrets)
DATABASE_URL=postgres://user:pass@localhost:5432/myapp
REDIS_URL=redis://localhost:6379
API_KEY=your-api-key-here
NODE_ENV=development
# .env.local (DO NOT COMMIT - actual secrets)
DATABASE_URL=postgres://prod:secret@prod-db:5432/myapp
API_KEY=sk_live_abc123
# .env.development / .env.production (environment defaults)
NEXT_PUBLIC_API_URL=http://localhost:3000/api
LOG_LEVEL=debug
Pattern 2: Zod Validation at Startup
// Source: https://zod.dev/
// src/config/env.ts
import { z } from 'zod';
const envSchema = z.object({
NODE_ENV: z.enum(['development', 'production', 'test']),
DATABASE_URL: z.string().url(),
REDIS_URL: z.string().url().optional(),
API_KEY: z.string().min(1),
PORT: z.coerce.number().default(3000),
LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});
// Validate on import - fails fast at startup
export const env = envSchema.parse(process.env);
// Type-safe access throughout app
console.log(env.DATABASE_URL); // string (validated)
Pattern 3: Next.js Environment Variables
// Source: https://nextjs.org/docs/app/building-your-application/configuring/environment-variables
// NEXT_PUBLIC_ prefix = exposed to browser
// Without prefix = server-only
// .env.local
DATABASE_URL=secret // Server only
NEXT_PUBLIC_API_URL=/api // Available in browser
// Usage in code
// Server component/API route
const dbUrl = process.env.DATABASE_URL;
// Client component
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
Pattern 4: Config Object Pattern
// Source: Best practice pattern
// src/config/index.ts
import { env } from './env';
export const config = {
isDev: env.NODE_ENV === 'development',
isProd: env.NODE_ENV === 'production',
server: {
port: env.PORT,
host: env.HOST || '0.0.0.0',
},
database: {
url: env.DATABASE_URL,
poolSize: env.DB_POOL_SIZE || 10,
},
auth: {
jwtSecret: env.JWT_SECRET,
tokenExpiry: '1h',
},
features: {
enableBeta: env.ENABLE_BETA_FEATURES === 'true',
},
} as const;
// Usage
import { config } from '@/config';
if (config.features.enableBeta) { /* ... */ }
Pattern 5: .gitignore for Env Files
# Environment files
.env
.env.local
.env.*.local
.env.development.local
.env.production.local
# Keep example
!.env.example
Pattern 6: Required vs Optional
// Source: https://zod.dev/
const envSchema = z.object({
// Required - app won't start without these
DATABASE_URL: z.string().url(),
JWT_SECRET: z.string().min(32),
// Optional with defaults
PORT: z.coerce.number().default(3000),
LOG_LEVEL: z.string().default('info'),
// Optional without default
SENTRY_DSN: z.string().url().optional(),
// Conditional (required in production)
REDIS_URL: z.string().url().optional()
.refine(
(val) => process.env.NODE_ENV !== 'production' || val,
'REDIS_URL required in production'
),
});
Anti-Patterns
- Hardcoded secrets - Always use environment variables
- Secrets in .env.example - Only placeholder values
- No validation - Fail fast with Zod at startup
- NEXT_PUBLIC_ for secrets - Exposes to browser
Verification Checklist
- .env.example committed with placeholders
- .env.local in .gitignore
- Zod validation at app startup
- Secrets not prefixed with NEXT_PUBLIC_
- Required vs optional clearly defined