Vercel deployment

Canonical pattern for Next.js apps on Vercel with GitHub previews, fnox-backed secrets, Neon, Vercel Blob, and Clerk. Reference implementation: the habitats repo (mise.toml vercel:sync, fnox.toml, Neon + Blob + Clerk).

For remote-server / pi / tmux setup see best-practices/GDE-006-local-environment.md. For Clerk domain and OAuth rules see best-practices/GDE-002-clerk.md. For the full fnox playbook see best-practices/GDE-003-fnox-secrets.md.

Defaults

One-time project setup

1. GitHub + Vercel

1. Create a Vercel project linked to the GitHub repo.
2. Settings → Git → Production Branch = main.
3. Leave Preview Deployments enabled for non-main branches and pull requests.
4. If the Next app is not at the repo root (e.g. app/ or web/):
5. Settings → General → Root Directory = that folder.
6. Enable including source files outside the root when using a pnpm workspace.
7. Add "npm:vercel" = "latest" (or a pin) to mise.toml tools; run mise install.
8. From the app directory: vercel link once. Keep .vercel/ gitignored.

2. vercel.json

Commit a minimal config next to the Next app (adjust path for monorepos):

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs"
}

Add crons only when the app needs them. Cron handlers must verify Authorization: Bearer $CRON_SECRET and stay on the public middleware allowlist.

3. Required mise tools and tasks

Pin Vercel CLI via mise. Copy the habitats-style tasks (see best-practices/GDE-003-fnox-secrets.md for the full sync script):

vercel:sync must use fnox export -f json and vercel env add "$KEY" "$ENV" --value "$VALUE" --yes. Never pipe values on stdin — empty strings get stored silently.

mise run vercel:sync                      # → Vercel Production (default)
mise run vercel:sync -- --env preview     # → Vercel Preview
mise run vercel:sync -- --env development # → Vercel Development / `vercel dev`

4. fnox.toml

Declare every runtime env var the app needs. Item title in 1Password = env var name. Non-secrets may use default = "...".

Minimum set for a typical app:

Optional but common: AI_GATEWAY_API_KEY, app-specific secrets, JWT template name as a fnox default.

Keep a committed .env.example that lists the same keys with comments for local / Preview / Production — no real values.

Environment matrix

Vercel has three scopes. Map them deliberately:

Blast radius: Prefer separate 1Password vaults (and Neon branches) for Preview vs Production so a leaked preview token cannot read prod. Use fnox profiles (FNOX_PROFILE=preview / prod) locally when syncing; see best-practices/GDE-003-fnox-secrets.md § Staging vs production isolation. Habitats currently runs a single vault with profiles commented out — fine for dogfood, not the long-term default for client work.

GitHub branch previews

1. Connect the repo in the Vercel dashboard (Git integration).
2. Every push to a non-production branch and every PR gets a Preview deployment built with the Preview env scope.
3. After changing Preview secrets: mise run vercel:sync -- --env preview, then push or redeploy so the build picks up new values.
4. NEXT_PUBLIC_* vars are baked at build time. Changing them requires a new deployment (Git push or vercel --prod --force / preview redeploy).
5. Allow preview origins where the framework requires it (e.g. Next server actions allowedOrigins including *.vercel.app).

Neon

• Prefer the Neon ↔ Vercel integration so both DATABASE_URL (pooled) and DATABASE_URL_UNPOOLED (direct) are created; still mirror them into 1Password and manage day-to-day via vercel:sync so 1P remains source of truth.
• App queries: pooled URL. Migrations / LISTEN / session features: unpooled.
• Preview isolation: a Neon branch (or separate project) whose connection strings live only in the Preview vault / Preview Vercel scope.
• Run migrations from a laptop against the target URL; do not rely on Vercel build steps for destructive schema changes unless the project documents that path explicitly.

# Example: migrate prod from laptop (fnox or explicit URL)
DATABASE_URL="$(fnox get DATABASE_URL_UNPOOLED)" pnpm db:migrate

Vercel Blob

1. Create a Blob store in the Vercel project (or reuse per-environment stores).
2. Put BLOB_READ_WRITE_TOKEN in the matching 1Password vault.
3. Sync with vercel:sync for each env scope that needs storage.
4. Prefer private blobs; serve through authenticated app routes (signed URL or stream), not public world-readable URLs for client data.
5. Health checks should report whether the blob token is present (boolean), not the token value.

Clerk: production vs staging / preview

Full rules: best-practices/GDE-002-clerk.md. On Vercel specifically:

Never put pk_test_ / sk_test_ in Vercel Production. The #1 prod outage pattern is shipping the dev instance to the live domain.

Sanity-check a publishable key:

echo "${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY#pk_live_}" | base64 -d
# → clerk.<client>.thefocus.ai for live; *.clerk.accounts.dev means DEV

Practical sync model:

1. Preview vault holds dev Clerk keys + staging Neon + preview Blob token.
2. Prod vault holds live Clerk keys + prod Neon + prod Blob token.
3. FNOX_PROFILE=preview mise run vercel:sync -- --env preview
4. FNOX_PROFILE=prod mise run vercel:sync (production)

If the project still uses one vault (habitats today), keep Clerk live keys only on items that you sync to Production, and never run a blind sync of test keys into --env production.

Daily operations

# 1. Rotate or edit in 1Password
op item edit DATABASE_URL --vault "<Project - Prod>" password='…'

# 2. Push to the right Vercel scope
mise run vercel:sync
# or: FNOX_PROFILE=preview mise run vercel:sync -- --env preview

# 3. Ship
git push origin main          # preferred: Git → Production
# or: mise run vercel:deploy

# 4. Verify
vercel env ls
curl -sS "https://<host>/api/health"

Health and cron

• Expose /api/health (or equivalent) that reports booleans for DB / Blob / Clerk config without leaking secrets.
• Cron routes: declare in vercel.json, protect with CRON_SECRET, exclude from Clerk auth.
• Long jobs: set maxDuration / Fluid Compute as needed; document in the app.

Anti-patterns

• Manual dashboard-only secrets with no fnox / 1Password source of truth.
• fnox exec (or installing fnox) as the Vercel build command.
• Dev Clerk keys in Production; live keys committed to .env or the repo.
• One Neon database shared by Preview and Production with write access from both.
• Syncing the entire monorepo vault into a Vercel project that only needs a subset (review vercel env ls after sync).
• Changing NEXT_PUBLIC_* and expecting running deployments to pick it up without a rebuild.
• Relying on Supabase-as-default for new Focus projects — prefer Neon unless the client already standardized on Supabase (document the exception).

New project checklist

• [ ] Vercel project linked to GitHub; Production branch main; Preview on
• [ ] Root Directory + vercel.json "framework": "nextjs"
• [ ] npm:vercel in mise; vercel link; .vercel/ gitignored
• [ ] Dedicated 1Password vault(s); fnox.toml; mise run setup
• [ ] vercel:sync / vercel:deploy / vercel:preview tasks
• [ ] Neon: pooled + unpooled URLs; Preview branch planned
• [ ] Blob token(s) in fnox
• [ ] Clerk: separate prod instance; test keys only in Preview/Development
• [ ] .env.example matches fnox keys; health endpoint exists
• [ ] mise run vercel:sync + smoke deploy; vercel env ls reviewed
• [ ] Custom domain + Clerk DNS per best-practices/GDE-002-clerk.md when going live