skills/fullstack-dev/references/environment-management.md

Environment & CORS Management

Patterns for managing environment variables, API URLs, and CORS configuration across frontend and backend stacks.

---

Standard Environment Pattern

# .env.local (gitignored, for local dev)
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_WS_URL=ws://localhost:3001

# Staging (set in Vercel/CI)
NEXT_PUBLIC_API_URL=https://api-staging.example.com

# Production (set in Vercel/CI)
NEXT_PUBLIC_API_URL=https://api.example.com

---

Environment Variable Rules

✅ API base URL from environment variable — NEVER hardcoded
✅ Prefix client-side vars with NEXT_PUBLIC_ (Next.js) or VITE_ (Vite)
✅ Backend URL = server-only env var (for SSR calls, not exposed to browser)
✅ CORS on backend: explicit list of allowed origins per environment

❌ Never use localhost URLs in production builds
❌ Never expose backend-only secrets with NEXT_PUBLIC_ prefix
❌ Never commit .env.local (commit .env.example with placeholders)

---

CORS Configuration

// Backend: environment-aware CORS
const ALLOWED_ORIGINS = {
  development: ['http://localhost:3000', 'http://localhost:5173'],
  staging: ['https://staging.example.com'],
  production: ['https://example.com', 'https://www.example.com'],
};

app.use(cors({
  origin: ALLOWED_ORIGINS[process.env.NODE_ENV || 'development'],
  credentials: true,  // needed for cookies (auth)
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
}));

---

Common Issues

Issue 1: "CORS error in browser but works in Postman"

Cause: CORS is a browser security feature. Postman/curl skip it.

Fix:

1. Backend must return Access-Control-Allow-Origin: https://your-frontend.com
2. For cookies/auth: credentials: true on both sides
3. Check that preflight OPTIONS request returns correct headers

Issue 2: "Environment variable undefined in browser"

Cause: Missing NEXT_PUBLIC_ or VITE_ prefix for client-side access.

Fix: Client-side vars MUST have the framework prefix. Rebuild after adding new env vars (they are embedded at build time).

Issue 3: "Works locally, fails in staging"

Cause: Different origins, missing CORS config for staging domain.

Fix: Add staging origin to ALLOWED_ORIGINS, verify env vars are set in deployment platform.