Runbook — Vercel deploy for @hatch/web

Owner: Raj On-call surface: gohatch.fun (and preview deploys at *.vercel.app)

Hatch ships the landing page + every user-facing web surface via Vercel. API + worker live on Railway (Sprint A.2). This runbook covers only the Vercel side.

1. First-time project link

Prereq: npm i -g vercel (or use npx vercel ad-hoc).

cd /Users/rajkaria/Projects/hatch
vercel login
vercel link          # bind this repo to a Vercel project

When Vercel asks:

• Scope: personal (or your team).
• Project name: hatch-web.
• Root directory: keep the repo root (monorepo-aware — see vercel.json).
• Override settings: No. Everything is already in vercel.json.

The link writes .vercel/project.json — add it to .gitignore (already done) and keep it untracked. It's machine-local.

2. GitHub integration (preferred production path)

From the Vercel dashboard:

1. Import Project → GitHub → rajkaria/hatch.

2. Framework Preset: Next.js.

3. Root directory: leave as . (the repo root).

4. Build & Output settings: already driven by vercel.json — don't override.

5. Environment variables (Production + Preview):

   Name	Value
   NEXT_PUBLIC_API_BASE_URL	https://api.gohatch.fun once Railway is live
   NEXT_PUBLIC_WEB_BASE_URL	https://gohatch.fun

   Scoring keys (ANTHROPIC_API_KEY) do NOT go to the web project — they live on the API service (Railway).

6. Deploy.

Vercel will:

• Detect the pnpm + Turborepo layout (via packageManager in root package.json).
• Run pnpm install then pnpm turbo run build --filter=@hatch/web....
• Deploy apps/web/.next.

Push to main auto-deploys production. PRs get preview URLs.

3. Connect the domain

Once the first deploy is green:

1. Vercel → Project → Settings → Domains.
2. Add gohatch.fun.
3. Add www.gohatch.fun and set it to redirect to apex.
4. Vercel prints DNS records (A and/or CNAME). Paste them into Cloudflare (our registrar — Dep.4.4 / Dep.5.1).
5. Wait for DNS propagation (usually <5 min; up to 1h).
6. Vercel auto-provisions a Let's Encrypt cert.

4. Smoke test after first deploy

curl -I https://gohatch.fun/                     # expect 200
curl -I https://gohatch.fun/zh                   # expect 200, 中文 version
curl -s https://gohatch.fun/ | grep -q 'Hatch'   # wordmark present

Browser checks:

• Locale switcher toggles en ↔ zh.
• Theme toggle works.
• No console errors.
• Lighthouse score ≥ 95 performance, ≥ 95 a11y.

5. Rollback

vercel rollback   # interactive; pick the last known-good deploy

Or via the dashboard: Deployments → pick a good one → Promote to Production.

6. Known gotchas

• pnpm lockfile missing? Our installCommand uses --frozen-lockfile=false so first-deploy succeeds. Once a lockfile lands on main, switch to pnpm install --frozen-lockfile via env var VERCEL_INSTALL_COMMAND in Project Settings. (Don't silently flip it in vercel.json without verifying CI green.)
• Monorepo build stale? turbo-ignore skips web builds when nothing in the web graph changed. To force a rebuild: Vercel dashboard → Redeploy → uncheck "Use existing Build Cache".
• Env var forgotten? Preview deploys use their own env var scope. Missing vars fail at runtime, not build — check Logs.