curiositech/environment-config-manager

Environment Config Manager

Expert in 12-factor configuration management, feature flags, and environment-specific config across dev, staging, and production.

Activation Triggers

Activate on: "environment variables", "ConfigMap", "feature flags", "12-factor config", "dotenv setup", "config per environment", "runtime configuration", "config validation", "environment parity"

NOT for: Secret storage → secret-management-expert | IaC provisioning → terraform-module-builder | CI/CD variables → github-actions-pipeline-builder

Quick Start

1. Separate config from code — no hardcoded URLs, ports, or feature toggles in source
2. Define config schema — typed validation with defaults (zod, envalid, convict)
3. Layer environments — base config overridden by environment-specific values
4. Implement feature flags — runtime toggleable features without deployment
5. Validate on startup — fail fast if required config is missing or invalid

Core Capabilities

| Domain | Technologies | |--------|-------------| | Validation | zod, envalid, @t3-oss/env-nextjs, convict, joi | | Feature Flags | LaunchDarkly, Unleash, Flagsmith, Statsig, simple JSON flags | | K8s Config | ConfigMap, ExternalSecret, Kustomize overlays | | Local Dev | dotenv, direnv, 1Password CLI (op run), docker-compose env | | Runtime Config | etcd, Consul KV, AWS AppConfig, Firebase Remote Config |

Architecture Patterns

Typed Config Validation (TypeScript)

// config/env.ts — fail fast on invalid config
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  FEATURE_NEW_CHECKOUT: z.coerce.boolean().default(false),
  API_RATE_LIMIT: z.coerce.number().default(100),
});

export type Env = z.infer<typeof envSchema>;

// Parse and validate — throws on startup if invalid
export const env = envSchema.parse(process.env);

Environment Layering

.env                    # Base defaults (committed, no secrets)
.env.development        # Dev overrides (committed)
.env.staging            # Staging overrides (committed, no secrets)
.env.production         # Production overrides (committed, no secrets)
.env.local              # Local overrides (gitignored, may have secrets)

Loading order (later overrides earlier):
  .env → .env.{NODE_ENV} → .env.local

Secrets come from secret store, NOT .env files:
  DATABASE_URL → AWS Secrets Manager / Vault
  API_KEY → External Secrets Operator

Feature Flag Architecture

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Client     │    │  Flag Store   │    │   Admin UI   │
│  SDK/hook    │───▶│  (Unleash/   │◀───│  Toggle flags │
│              │    │   LaunchDarkly)│    │  per env     │
└──────────────┘    └──────────────┘    └──────────────┘

Evaluation: user context + flag rules → boolean/variant
  - Percentage rollout: 10% of users see new feature
  - User targeting: beta users see new feature
  - Environment: enabled in staging, disabled in production
  - Kill switch: instantly disable without deployment

Anti-Patterns

1. Config in code — hardcoded localhost:5432 or if (env === 'production') scattered across files. Centralize all config in one validated module.
2. Secrets in .env files committed to Git — even example files leak secret formats. Use .env.example with placeholder descriptions, not values.
3. No config validation — trusting process.env.PORT is a valid number. Validate and coerce all config at startup with a schema library.
4. Feature flags as permanent config — flags accumulate and become tech debt. Set expiration dates and clean up old flags quarterly.
5. Environment-specific code paths — if (process.env.NODE_ENV === 'production') for business logic. Use feature flags instead; environment should only affect infrastructure config.

Quality Checklist

[ ] All config loaded from environment variables (12-factor compliant)
[ ] Config schema validated on application startup (fail fast)
[ ] .env.example documents all required variables with descriptions
[ ] No secrets in committed .env files
[ ] .env.local in .gitignore
[ ] Feature flags have owner, description, and expiration date
[ ] Dev/staging/production parity maintained (same config keys)
[ ] Config changes do not require code deployment
[ ] Default values sensible for development (zero-config local setup)
[ ] ConfigMaps and Secrets separated in Kubernetes
[ ] Feature flag cleanup tracked in backlog
[ ] Runtime config changes logged and auditable