env-configuration

Apply when managing application configuration: environment variables, secrets management, and config validation.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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.
nameenv-configuration
descriptionApply when managing application configuration: environment variables, secrets management, and config validation.
version1.0.0
tokens~550
confidencehigh
- https//nextjs.org/docs/app/building-your-application/configuring/environment-variables
last_validated2025-01-10
next_review2025-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