Deploying an Astro site to Vercel

If your Astro site is fully static, Vercel will deploy it with zero configuration — connect the repo, it detects Astro, runs astro build, and serves the output. But most real sites end up with at least one server-rendered route or an API endpoint eventually, and that’s where people hit a wall because they never installed an adapter and assumed static output would handle everything.

Install the Vercel adapter explicitly rather than relying on auto-detection to configure it for you:

npx astro add vercel

That command updates astro.config.mjs with the adapter import and sets output: 'server' (or 'hybrid' depending on your Astro version, check what it actually writes rather than assuming). If you only have a couple of dynamic routes and want the rest of the site to stay static, hybrid output with per-page export const prerender = true overrides is the setup I use most — static by default, dynamic only where a page explicitly opts out.

Environment variables are the thing that actually causes deploy failures, not the adapter. Vercel’s dashboard separates variables by environment (Production, Preview, Development), and it’s easy to add a key to Production and forget Preview, which means your PR preview deployments fail or silently behave differently than production. Set any variable that’s genuinely needed across all three, and be deliberate about the ones that shouldn’t be — a production API key has no business being available in Preview deployments that anyone with a PR link can open.

Build settings rarely need touching, but if your project lives in a subdirectory of a monorepo, set the Root Directory in the Vercel project settings rather than trying to hack around it with a custom build command — the latter works until someone adds a workspace-level script and the paths break.

Custom domains are a DNS change plus a verification step on Vercel’s side, and the one gotcha is propagation time paired with impatience — I’ve seen people assume a domain is broken and start reconfiguring fifteen minutes after a DNS change, when it just hadn’t propagated yet. Check the actual DNS records with a lookup tool before touching Vercel’s config again.

Once it’s deployed, turn on preview deployments for every PR if you haven’t already. It’s on by default for GitHub-connected projects, but it’s worth confirming, because it’s the single feature that makes client review painless.