Environment Variables
Required keys by app, build-time vs runtime, and secrets policy.
Environment variables connect UXDL apps to Cognito, databases, S3, FCM, email providers, and observability tools. Every repo ships an .env.example — this page explains the conventions across projects.
Naming rules
| Type | Prefix | Resolved | Exposed to browser |
|---|---|---|---|
| Public (client) | NEXT_PUBLIC_ | Build time | Yes — embedded in JS bundle |
| Server runtime | None | Runtime | No |
| Secret | None | Runtime (vault) | Never |
Frontend (Next.js)
Typical keys for UXDL web apps:
# App
NEXT_PUBLIC_APP_ENV=local # local | alpha | beta | production
NEXT_PUBLIC_API_URL=http://localhost:4000
# AWS Cognito — see /integrations/cognito
NEXT_PUBLIC_COGNITO_USER_POOL_ID=us-east-1_xxxxx
NEXT_PUBLIC_COGNITO_CLIENT_ID=xxxxxxxx
NEXT_PUBLIC_COGNITO_DOMAIN=auth.uxdl.com
# Firebase / FCM (web push) — see /integrations/fcm
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FCM_VAPID_KEY=
# Observability (optional locally)
NEXT_PUBLIC_SENTRY_DSN=| Variable | Environment | Notes |
|---|---|---|
NEXT_PUBLIC_API_URL | All | Points to Express API — localhost:4000 locally, api.uxdl.com in prod |
| Cognito vars | Per env | Separate app client per Alpha / Beta / Prod |
| Firebase vars | Per env | Same Firebase project or separate for prod — confirm with platform team |
Setup guide: React + Next.js.
Backend (Express)
Typical keys for UXDL API services:
# Server
NODE_ENV=development
PORT=4000
CORS_ORIGIN=http://localhost:3000
# Database — pick one per service
DATABASE_URL=postgres://uxdl:uxdl@localhost:5432/uxdl_local
MONGODB_URI=mongodb://localhost:27017/uxdl_local
SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
# Auth — Cognito JWT validation
COGNITO_REGION=us-east-1
COGNITO_USER_POOL_ID=
# AWS
AWS_REGION=us-east-1
S3_BUCKET=uxdl-uploads-alpha
CLOUDFRONT_DOMAIN=cdn.uxdl.com
# Push — FCM (server)
FCM_PROJECT_ID=
FCM_CLIENT_EMAIL=
FCM_PRIVATE_KEY=
# Email — one provider per environment
EMAIL_PROVIDER=ses # ses | sendgrid | brevo
EMAIL_FROM=noreply@uxdl.com
SENDGRID_API_KEY= # if EMAIL_PROVIDER=sendgrid
BREVO_API_KEY= # if EMAIL_PROVIDER=brevo
# Observability
SENTRY_DSN=
OTEL_EXPORTER_OTLP_ENDPOINT=
AXIOM_TOKEN=
AXIOM_DATASET=| Variable | Secret? | Source |
|---|---|---|
DATABASE_URL | Yes (prod) | ECS task secret / local Docker |
SUPABASE_SERVICE_ROLE_KEY | Yes | Vault — bypasses RLS |
FCM_PRIVATE_KEY | Yes | Firebase service account JSON |
SENDGRID_API_KEY / BREVO_API_KEY | Yes | Vendor console |
| S3 / SES (prod) | No key needed | ECS task IAM role |
Setup guide: Backend Overview → Node or Python. Vendor setup: Integrations Overview.
By environment
| Local | Alpha | Beta | Production | |
|---|---|---|---|---|
| Config file | .env.local | CI / ECS secrets | CI / ECS secrets | ECS secrets |
| API URL | localhost:4000 | Alpha preview URL | api-beta.uxdl.com | api.uxdl.com |
| Cognito client | Dev client | PR preview client | Beta client | Prod client |
| S3 bucket | Alpha bucket or local skip | Alpha bucket | Beta bucket | Prod bucket |
| Email provider | Brevo sandbox or SES sandbox | Brevo / SES | SES | SES |
Details: Environments.
Local setup workflow
cp .env.example .env.local
# Fill values from password manager or ask your onboarding buddy.env.local is gitignored. Never commit it, paste it in Slack, or add it to PRs.
Documentation requirements (every repo)
Each project's .env.example must list:
- Every required variable with a placeholder value (never real secrets)
- Whether it is public (
NEXT_PUBLIC_) or server-only - Which environments need it (local, alpha, beta, prod)
- Vault path or owner for secrets — e.g.
vault://prod/uxdl-api/database-url
Rotating secrets
When a secret rotates:
- Update the value in AWS Secrets Manager / vault
- Redeploy affected ECS services (or restart local dev)
- Never rotate by editing committed files