Pushpaka

Pushpaka — The Flying Chariot (Vercel Frontend Deploys)

Pushpaka Vimana flew its passenger wherever intended, instantly and without harm. A frontend deploy should feel the same: every push travels, only main lands in production, and any landing can be undone in one motion.

Environments

• Three Vercel environments, three configurations: Production (main), Preview (every other branch/PR), Development (vercel dev/local). Never share backing services between Production and Preview.
• Previews point at a staging FastAPI service and a staging Supabase project — a preview that writes to production data is an incident, not a convenience (see dhanvantari).
• Promotion path is git: merge to main deploys production. No vercel --prod from laptops once the git integration exists; the deploy history should equal the commit history.

Environment variables

• Set per environment in the Vercel dashboard/CLI, mirrored in a committed .env.example with every key name and a comment — values live in Vercel, names live in the repo (see kubera).
• Anything prefixed VITE_/NEXT_PUBLIC_ is compiled into the public bundle. The Supabase URL and anon key belong there; nothing else does. Adding a NEXT_PUBLIC_ var is a security review question, not a naming choice.
• The frontend holds no provider API keys, no service-role key, under any prefix — AI calls go through FastAPI (see vayu).
• Env var changes require a redeploy to take effect — build-time inlining means editing the dashboard alone changes nothing. Change var → redeploy → verify.
• vercel env pull for local sync; local .env* files stay gitignored.

Preview discipline

• Every PR gets its preview URL exercised before review approval: the change is reviewed running, not imagined from the diff.
• The preview URL pattern is registered in FastAPI's CORS regex (see vayu) — "works locally, CORS-fails on preview" is a configuration bug you've chosen to keep.
• Preview deployments stay protected (Vercel Authentication) unless a stakeholder demo requires otherwise; share links deliberately.

Build hygiene

• The production build runs typecheck and lint as part of build — a type error is a failed deploy, not a warning in CI you scroll past (see brahma for the pipeline).
• Pin the Node major version in project settings so local, CI, and Vercel build identically.
• Build must be deterministic from a clean checkout: committed lockfile, no postinstall network surprises, no writes outside the output directory.
• Watch bundle size on merge: a dependency that doubles the chat bundle is a performance regression (see garuda).

Domains, caching, headers

• Apex + www both configured, one canonical (pick www or apex, redirect the other). TLS is automatic — never bypass a certificate warning by "waiting it out"; fix DNS.
• Static assets are content-hashed and immutable-cached by default — don't fight it; never cache HTML beyond revalidation. If you add Cache-Control headers manually, you must be able to explain the stale-page story.
• Security headers set project-wide: X-Content-Type-Options: nosniff, Referrer-Policy, a CSP at least in report-only to start (see muruka).

Rollback & incidents

• Rollback is instant and blameless: promote the previous Ready deployment from the dashboard/CLI first, diagnose second (see dhanvantari).
• After rollback, main still contains the bad commit — revert it in git immediately, or the next merge redeploys the incident.
• Frontend and backend deploys are independent (Vercel vs Render): ship changes backward-compatibly — the API additive-first (see vayu), the frontend tolerant of the previous API version — because for some minutes, old frontend will talk to new backend or vice versa.

Observability

• Enable Vercel Analytics/Speed Insights (or your chosen RUM) on production only — Core Web Vitals from real users are the frontend's SLO inputs (see surya).
• A frontend error tracker (e.g. Sentry) with release tagging tied to the deploy — "which deploy introduced this" should be a lookup, not an investigation (see durga).

Before going live — checklist

• Previews point at staging Supabase + staging FastAPI, never production
• .env.example matches Vercel env keys; no secret under a public prefix
• Typecheck + lint fail the build; Node version pinned; lockfile committed
• Preview URL pattern in backend CORS; preview exercised before merge
• Canonical domain + redirect configured; security headers present
• Rollback rehearsed once: previous deployment promoted and verified