Skip to content
StackQuay
EN繁中

Playbook · Vercel

Deploy your site on Vercel — preview first

Put a Next.js (or similar) site on a preview URL, then promote to production when you are ready.

2026-10-16

Who it’s for / not for

ForNot for
People with a Next.js app who want a preview URLTeams that need VPC / compliance certification, or multi-region ops runbooks
Agent-led microbusinesses (bot drafts deploy checklist + SEO; human owns Vercel login, secrets, domain money, prod flip)Anyone treating this page as billing / legal advice
Operators okay with *.vercel.app previews first, custom domain laterA host that is not Vercel
Hosting only: a project and a clickable preview URLPlugin, MCP, or AI Gateway — that is Vercel agent toolchain, not this page

Stack (spine only)

Secondary (skip overnight): AI Gateway, Token Pass, Daemons, Rolling Releases deep-dive.

  • Vercel project — groups deployments, env vars, domains (projects overview)
  • Preview + Production environments — Local → Preview → Production (deployments overview)
  • Environment variables — Config vs Secret; scoped per environment (env docs)
  • Optional Git — push/PR → automatic preview; production branch (usually main) → production when you allow it
  • Later (not this page’s job): Resend / Stripe live keys in Production env only after those playbooks’ human gates

Bot vs human

Bot doesHuman must do
Draft this playbook + SEO + checklistCreate / own the Vercel account + team
Suggest a project name and which environment variables to addPaste real API keys only in Dashboard / CLI as Secret — never into chat or git
Run / document preview deploy steps when askedClick Promote to Production when you are ready
Flag domain / DNS steps as STOPBuy a domain yourself when you want a custom name
Never commit .env / secret valuesKeep Production branch protection + Deployment Protection as you prefer

Numbered steps

  1. Have a project that already builds locally. This hub should pass npm run build on your machine first. Vercel creates a deployment from a successful build (deployments overview).
  2. Create or link a Vercel project. Pick one: Git — import the repo so each commit/PR can get a preview URL. CLI — npm i -g vercel then in the project root vercel (creates .vercel/ with project IDs — keep out of secrets). Vercel Drop — drag folder to vercel.com/drop for a quick prototype. Prefer Git or CLI so previews iterate cleanly.
  3. Add environment variables. Dashboard → Project → Settings → Environment Variables, or CLI (vercel env add). Choose Config vs Secret. Start with Preview and Development. Add Production values when you promote. Changes apply only to new deployments. Pull local: vercel env pull → .env.local (gitignored). Never commit real keys.
  4. Ship a Preview deployment and open the URL. Git: push a branch or open a PR. CLI: vercel / vercel deploy (without --prod) → a unique preview URL. Click the routes you care about. Preview deployments are not indexed by search engines by default.
  5. Iterate on Preview only. Fix copy / design via PR or new preview deploys. Use Dashboard → Deployments → Inspect / Logs / Redeploy as needed. Do not assign a custom production domain yet.
  6. STOP before custom domain. Every project gets a *.vercel.app URL first (working with domains). Custom domains: buy via Vercel or third-party, then Project Settings → Domains (domains overview). You buy or renew the domain. An agent can draft a DNS checklist after you own the name.
  7. STOP before production promote. Production happens when you push/merge to the Production Branch (often main), run vercel deploy --prod, or Promote a preview (promote guide). Promote rebuilds with Production env vars (preview values are not reused). You run --prod, Promote, or merge to the production branch when you are ready. Rollback exists (vercel rollback) — you run that too.

Failure modes / caveats

  • Secrets in git — .env, .vercel team tokens, or pasted keys in markdown = rotate immediately; use Secret env type.
  • Accidental production — vercel --prod / merge to main with auto-assign domains live; human must verify Project Environments settings.
  • Preview works, prod broken — different Production env vars; promote rebuilds with production values. Audit with vercel env ls production vs preview.
  • Env size limits — 64 KB total per deployment on supported runtimes; Edge runtime 5 KB per variable (env docs).
  • Domain not verified / Invalid Configuration — DNS mismatch; fix in registrar or Vercel Domains UI.
  • Buying domain on wrong team — domains owned at team level; project assignment is separate.
  • No fake traffic claims — preview URL ≠ production SEO; don’t invent visitor counts.
  • Billing — Hobby vs Pro limits / free first-year domain offers change; human must verify current pricing.

Newsletter CTA

When the preview looks right, promote it yourself. Next checklist: Resend or Stripe Payment Links.

Human must verify

  1. Vercel account / team ownership and who can deploy to Production.
  2. Production Branch name and whether auto-assign custom domains is on.
  3. Which env vars exist in Preview vs Production (no leftover test keys in prod).
  4. Secret vs Config classification for any API key.
  5. Current Hobby/Pro limits and whether a “free domain” offer applies to *your* team.
  6. DNS records / nameserver path for any custom domain you choose (Vercel-bought vs third-party).
  7. SSL / domain verification status before announcing a custom URL.
  8. You decide when to buy a domain, run vercel deploy --prod / promote, or publish.

Doc gaps

Exact Hobby free-tier quotas and live domain prices were not frozen into this draft (marketing offers change). CLI flag nuances beyond the cited promote/env pages — confirm with vercel --help on your installed CLI version before scripting.

Docs cited

Related playbooks

Newsletter formAll playbooks