Beginner
How to deploy an Astro site on Vercel
Quick Answer
Push your Astro project to a Git repo, import it into Vercel via dashboard or run
vercel CLI for automatic detection and deployment of static sites. For SSR, run astro add @astrojs/vercel first. Builds output to dist/ and go live on a .vercel.app 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)
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.Tip
Commit your lockfile (
package-lock.json or pnpm-lock.yaml) 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.
Tip
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.Tip
Check build logs in the Deployments tab for details.
6
CLI: Install Vercel CLI
In your terminal, install globally with
npm install -g vercelpnpm 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.Tip
Use
vercel --prod for production deployments.8
Enable SSR (optional)
For server-side rendering, run
astro add @astrojs/vercelastro.config.mjs with output: 'server' and adapter: vercel(). Redeploy using UI or CLI steps above.Tip
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.Tip
Never commit
.env 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" }] }]
}Troubleshooting
Build fails with UNMET DEPENDENCY or missing modules
Clear cache and reinstall:
rm -rf node_modules .astro dist package-lock.json
npm cache clean --force
npm install
npm run buildrm -rf node_modules .astro dist pnpm-lock.yaml && pnpm store prune && pnpm install.Node version mismatch causing build errors
Verify local Node with
node --version (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
PUBLIC_ prefix for client-side. Ensure .env is gitignored. Redeploy.Deployment stuck or cache pollution
Check build logs in Vercel dashboard Deployments tab. Clear Vercel cache via
vercel --force or dashboard redeploy. Verify astro build succeeds locally.SSR not rendering; stuck on static
Confirm
astro add @astrojs/vercel ran and astro.config.mjs has output: 'server'. Redeploy.Ready to get started with Vercel?
Put this tutorial into practice. Visit Vercel and follow the steps above.
Visit Vercel →