Configuration Across Two Deployables

# Frontend (.env.local) — NEXT_PUBLIC_ is inlined into the bundle
NEXT_PUBLIC_API_URL=https://api.aicancode.org
NEXT_PUBLIC_RAZORPAY_KEY_ID=rzp_live_xxx      # publishable by design
NEXT_PUBLIC_POSTHOG_KEY=phc_xxx

# Backend (Fly secrets) — never leaves the server
DATABASE_URL=postgres://...
JWT_SECRET=...
RAZORPAY_KEY_SECRET=...
OPENAI_API_KEY=...

// The rule: NEXT_PUBLIC_ (or VITE_) is a declaration that this value
// is public. It is substituted at BUILD time and lives in the shipped
// JavaScript forever — including in every previously deployed bundle.

// So a secret placed there is not "leaked if someone looks", it is
// published. Rotate it; you cannot unpublish it.

// A server-only variable is simply unprefixed, and reading it from a
// client component returns undefined by design:
process.env.JWT_SECRET        // undefined in the browser

// The dangerous middle: Next.js server components and route handlers
// CAN read secrets — and importing such a module into a client
// component is how a secret ends up in the bundle. Mark them:
import 'server-only'          // build fails if a client imports it

# Backend — parse the whole environment once, at import time
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    DATABASE_URL: PostgresDsn
    JWT_SECRET: str = Field(min_length=32)
    ALLOWED_ORIGINS: list[str]
    ENVIRONMENT: Literal["development", "staging", "production"]
    RAZORPAY_KEY_ID: str
    LOG_LEVEL: str = "INFO"                    # a sane default

settings = Settings()      # missing or malformed -> crash on boot

# Without this, a missing JWT_SECRET is discovered by the first user
# who tries to log in, hours after the deploy.

// Frontend — the same idea
const env = z.object({
  NEXT_PUBLIC_API_URL: z.string().url(),
}).parse({ NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL })
// Run it at build time so a missing variable fails the build.

// Every process.env value is a string. Coerce and validate:
PORT: int = 8000                # not "8000"
DEBUG: bool = False             # "false" is truthy as a string

# Local
.env.local          # gitignored, real values
.env.example        # COMMITTED, every key with a placeholder —
                    # this is the onboarding document

# Vercel: per-environment values in the dashboard or CLI
vercel env add NEXT_PUBLIC_API_URL production
# Production, Preview and Development are separate sets. Preview
# builds must point at a staging API, not production.

# Fly: secrets are encrypted and injected as env vars
flyctl secrets set JWT_SECRET=... -a tool-hub-api     # triggers a restart
flyctl secrets list                                    # names only, never values

# Rules:
#   - .env* in .gitignore, except .env.example
#   - never paste a secret into chat, a ticket or a log line
#   - a leaked secret is rotated, not deleted from history — assume
#     it was captured the moment it was exposed
#   - separate credentials per environment, so a staging leak is not
#     a production incident

# Detection, because this happens to everyone eventually:
gitleaks detect            # in CI, and as a pre-commit hook

# And be careful with logging: a URL containing ?key=... appears in
# access logs, exception traces and error trackers. Put credentials
# in headers, never in query strings.