Deploy on Vercel
Overview
Ship this project to Vercel with correct env vars, build settings, and production checks. Applies to Next.js App Router and Express API boilerplates in this catalog.
Pre-deploy Checklist
-
npm run buildpasses locally -
npm testpasses - Secrets are in Vercel project settings, not in git
- No debug logging of tokens or PII
- Production URL and env documented in README
Next.js App Router
- Connect the Git repo in the Vercel dashboard (or
vercel link+vercel deploy). - Framework preset: Next.js (auto-detected).
- Set server-only env vars in Vercel — never prefix secrets with
NEXT_PUBLIC_. - Use Server Components and Route Handlers for privileged logic.
- After deploy, smoke-test critical routes and API handlers.
Common issues:
- Build fails on server/client boundary — find
"use client"leaks of server modules. - Missing env at build time — set vars for Production and Preview if needed.
Express API (serverless)
- This boilerplate ships
vercel.jsonrouting to the Express app. - Set
NODE_ENV=productionand API secrets in Vercel env settings. - Keep handlers stateless — no in-memory session stores across invocations.
- Run integration tests against
vercel devbefore promoting to production.
Common issues:
- Cold starts — keep startup lean; lazy-load heavy deps.
- Body size / timeout — respect Vercel function limits; return 413/504 gracefully.
Environment Variables
| Kind | Where |
|---|---|
| Secrets (API keys, DB URLs) | Vercel → Settings → Environment Variables (Production) |
| Public config (analytics ID) | NEXT_PUBLIC_* only when safe for browsers |
| Local dev | .env.local (gitignored) — never commit |
Post-deploy
- Hit health or home route; confirm expected status.
- Check Vercel function logs for startup errors.
- Run
bwai scan-projecton the deployed repo clone if skills changed.
Rollback
Use Vercel instant rollback to the previous production deployment if smoke tests fail. Fix forward only after identifying root cause.
Anti-patterns
- Committing
.envor Vercel tokens to git. - Using production secrets in Preview without understanding exposure.
- Deploying with a red test suite or skipped security review on auth changes.


