# Pushpaka

> Vercel deployment standards for the React frontend — environments, env vars, preview deployments, domains, caching, and rollback. Use when deploying the frontend, configuring Vercel projects or environment variables, debugging a Vercel build or preview, or setting up domains and rollbacks.

- Skill: `arjuncrevathi/pushpaka` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arjuncrevathi/pushpaka`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arjuncrevathi/pushpaka/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: arjuncrevathi (https://skillmd.com/u/arjuncrevathi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arjuncrevathi/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