79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```typescript
|
|
// 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.
|