V Vercel

How to deploy Astro site on Vercel

beginner 8 min read Updated 2026-03-13
Quick Answer

Push your Astro project to a Git repo, import it into Vercel via dashboard or run <code>vercel</code> CLI for automatic detection and deployment of static sites. For SSR, run <code>astro add @astrojs/vercel</code> first. Builds output to <code>dist/</code> and go live on a <code>.vercel.app</code> URL in ~1 minute.

Prerequisites

  • Vercel account
  • Astro project with dependencies installed
  • Git repository (GitHub, GitLab, or Bitbucket)
  • Node.js (version 18.x or 20.x recommended)

Step-by-Step Instructions

1

Prepare your Astro project

Ensure your Astro project is set up with all dependencies installed via npm install or equivalent. Create a .gitignore file excluding node_modules, .astro, dist, and .env. For local testing, run npm run dev to verify on localhost:4321, then npm run build to generate dist/ output.
Commit your lockfile (<code>package-lock.json</code> or <code>pnpm-lock.yaml</code>) to ensure consistent dependencies on Vercel.
2

Push to Git repository

Initialize Git if needed with git init, add files via git add ., commit with git commit -m "Initial commit", and push to a remote repository on GitHub, GitLab, or Bitbucket using git remote add origin <repo-url> followed by git push -u origin main.
3

Website UI: Access Vercel Dashboard

Log in to your Vercel account at vercel.com/dashboard. If connecting GitHub for the first time, authorize Vercel to access your repositories when prompted.
4

Website UI: Import project

Click Add New Project in the dashboard. Select your Astro repository from the list of GitHub (or other) repos. Vercel auto-detects the Astro framework, setting Framework: Astro, Build command: astro build, and Output directory: dist.
No changes needed for static sites; proceed with defaults.
5

Website UI: Deploy

Click the Deploy button. Vercel clones the repo, installs dependencies, runs the build, and hosts dist/ on its CDN. Your site deploys in ~1 minute to a unique .vercel.app URL. Subsequent pushes to branches create Preview Deployments; main branch updates trigger Production Deployments.
Check build logs in the Deployments tab for details.
6

CLI: Install Vercel CLI

In your terminal, install globally with 
npm install -g vercel
(or pnpm add -g vercel). Verify with vercel --version.
7

CLI: Run deployment

Navigate to your project root and run vercel. Vercel detects Astro automatically. When prompted Want to override the settings? [y/N], enter N to accept defaults. Deployment completes with a live .vercel.app URL.
Use <code>vercel --prod</code> for production deployments.
8

Enable SSR (optional)

For server-side rendering, run 
astro add @astrojs/vercel
. This installs the adapter and updates astro.config.mjs with output: 'server' and adapter: vercel(). Redeploy using UI or CLI steps above.
Static sites need no adapter unless using Vercel-specific features like Image Optimization.
9

Configure environment variables

In Vercel dashboard, go to your project Settings > Environment Variables. Add vars from your local .env (e.g., PUBLIC_API_KEY=xxx for client-side). Use PUBLIC_ prefix for client access. Redeploy to apply.
Never commit <code>.env</code> to Git.
10

Advanced: Custom vercel.json

Create vercel.json in project root to override settings, e.g., add headers: 
{
  "headers": [{ "source": "/(.*)", "headers": [{ "key": "Cache-Control", "value": "public" }] }]
}
. Commit and redeploy.

Common Issues & Troubleshooting

Build fails with UNMET DEPENDENCY or missing modules

Clear cache and reinstall: <pre><code>rm -rf node_modules .astro dist package-lock.json npm cache clean --force npm install npm run build</code></pre>. Commit updated lockfile. For pnpm: <code>rm -rf node_modules .astro dist pnpm-lock.yaml && pnpm store prune && pnpm install</code>.

Node version mismatch causing build errors

Verify local Node with <code>node --version</code> (use 18.x or 20.x). Set Vercel Node version in dashboard: Project Settings > General > Node.js Version.

Environment variables not working

Add vars in Vercel dashboard (Settings > Environment Variables) with <code>PUBLIC_</code> prefix for client-side. Ensure <code>.env</code> is gitignored. Redeploy.

Deployment stuck or cache pollution

Check build logs in Vercel dashboard Deployments tab. Clear Vercel cache via <code>vercel --force</code> or dashboard redeploy. Verify <code>astro build</code> succeeds locally.

SSR not rendering; stuck on static

Confirm <code>astro add @astrojs/vercel</code> ran and <code>astro.config.mjs</code> has <code>output: 'server'</code>. Redeploy.

Visit Vercel View Vercel Pricing