Deploy Astro to Vercel — complete walkthrough with custom domain

Deploying an Astro site to Vercel takes about 15 minutes. Custom domain setup adds another 15-30 minutes for DNS propagation. This guide covers every step, including the common gotchas.

Prerequisites

Before starting:

• Astro site working locally (npm run dev shows it in browser)
• Code pushed to a GitHub repository (private or public)
• GitHub account
• A custom domain (optional but recommended)

Step 1 — Push code to GitHub

If code isn’t on GitHub yet:

cd path/to/your/astro-site
git init
git add .
git commit -m "Initial commit"

Create a new repository on github.com. Then:

git remote add origin https://github.com/YOUR-USERNAME/REPO-NAME.git
git branch -M main
git push -u origin main

Verify code appears on GitHub.

Step 2 — Sign up for Vercel

1. Go to https://vercel.com
2. Click “Sign Up”
3. Choose “Continue with GitHub” (fastest — links your GitHub account automatically)
4. Authorize Vercel to access your repositories

No credit card required for the free (Hobby) tier.

Step 3 — Import your repository

1. On Vercel dashboard, click “Add New Project”
2. Select “Import Git Repository”
3. Find your Astro repo in the list
4. Click “Import”

Vercel auto-detects Astro. Framework preset shows “Astro”. Build command shows npm run build. Output directory shows dist.

No changes needed. Click “Deploy”.

Step 4 — Wait for first deploy

First deploy takes 60-120 seconds. Vercel:

1. Clones your repo
2. Runs npm install
3. Runs npm run build
4. Uploads the dist folder to their global CDN

When done, you get a URL like your-project-abc123.vercel.app. Site is live.

Step 5 — Verify deployment

Click the deployment URL. Site should load.

Test:

• Homepage renders correctly
• Navigation works
• Individual pages/articles load
• No console errors (open DevTools)

If broken, click “View Function Logs” and “Build Logs” for debug info.

Step 6 — Connect custom domain

Assuming you own yourdomain.com:

1. Vercel project → Settings → Domains
2. Enter yourdomain.com
3. Click “Add”

Vercel shows DNS records you need to add:

Type: A
Name: @
Value: 76.76.21.21

Type: CNAME
Name: www
Value: cname.vercel-dns.com

Exact values may vary — always use what Vercel displays for you.

Step 7 — Update DNS at your registrar

Go to your domain registrar (Namecheap, GoDaddy, Google Domains, Cloudflare, etc.):

Namecheap:

1. Domain List → Manage
2. Advanced DNS tab
3. Delete existing A / CNAME records for @ and www
4. Add the records Vercel gave you
5. Save

Cloudflare:

1. Select your domain
2. DNS → Records
3. Add A record: Name @, IPv4 76.76.21.21, Proxy status: DNS only (grey cloud)
4. Add CNAME: Name www, Target cname.vercel-dns.com, Proxy: DNS only

GoDaddy: Similar pattern under DNS settings.

Step 8 — Wait for DNS propagation

DNS changes propagate globally in 5 minutes to 48 hours (usually 30 min).

Check status: https://dnschecker.org — enter your domain, watch the map turn green.

Once propagated, Vercel automatically:

• Issues a free SSL certificate (Let’s Encrypt)
• Redirects http:// to https://
• Redirects www to non-www (or vice versa — configurable)

Your site is now live at https://yourdomain.com.

Step 9 — Configure auto-deploys

Already configured. From now on:

git add .
git commit -m "New article"
git push

Vercel detects the push, rebuilds, and deploys in 30-60 seconds. No manual step needed.

Preview deployments (a killer feature)

For every pull request, Vercel automatically creates a preview URL. Example:

• Merge to main → deploys to yourdomain.com
• Push to branch feature/new-header → deploys to feature-new-header-yourproject.vercel.app

Preview URLs let you test changes before merging. Comment on PRs, share with reviewers, catch issues.

Environment variables

For secrets (API keys, tokens):

1. Vercel project → Settings → Environment Variables
2. Add each variable
3. Choose which environments to expose it in (Production, Preview, Development)
4. Trigger a redeploy

In Astro code, access via import.meta.env.YOUR_VAR.

Never commit .env files to git. Vercel handles env vars separately.

Custom build settings (usually not needed)

If Astro isn’t auto-detected correctly:

Settings → Build & Development Settings:

• Framework Preset: Astro
• Build Command: npm run build
• Output Directory: dist
• Install Command: npm install
• Development Command: npm run dev

Common gotchas

Build fails with “command not found”

Likely a missing dependency in package.json. Ensure all imports are in dependencies (not just installed locally).

Fix locally, commit package.json changes, push.

Site loads but styles missing

Check the browser network tab. If CSS 404s, the build likely failed to include them. Run npm run build locally first — if it works locally, verify the same Node version is used on Vercel (Settings → Node.js Version).

404 on custom domain but works on vercel.app URL

DNS not fully propagated. Wait more, or check dnschecker.org.

“This deployment cannot be found”

Vercel URL structure changed. Use the current deployment URL from the Deployments tab.

Bandwidth exceeded warning

Free tier is 100 GB/month. For typical blogs, you’d need 500K+ monthly visitors to hit this.

If exceeded: upgrade to Pro ($20/month) OR migrate to Cloudflare Pages (unlimited bandwidth free).

Rollbacks

Deploy broke production? Rollback in one click:

1. Vercel project → Deployments
2. Find a previous working deployment
3. Click ⋯ → “Promote to Production”

Site reverts instantly. Fix locally, push new commit when ready.

Monitoring

Vercel provides free:

• Analytics (basic): page views, top pages, unique visitors
• Real-time logs
• Deployment status
• Web Vitals scores

For deeper analytics, add Google Analytics via a script tag in your BaseLayout.

Removing Vercel branding

Free tier: none. Sites don’t have “Powered by Vercel” or ads.

Only visible sign of Vercel: your site URL shows .vercel.app if you don’t use a custom domain.

Cost tracking

Free tier is generous:

• 100 GB fast data transfer/month
• Up to 200 deployments per day
• 6,000 build execution minutes/month
• 1 million serverless function invocations/month + 4 CPU hours of active compute
• 1 million edge requests/month
• Personal account — Team features require Pro

Overage costs are shown clearly if you approach limits. Set up email alerts: Settings → Notifications → Enable “usage alerts”

When to upgrade to Pro

Move to Vercel Pro ($20/user/month) when:

• Consistent bandwidth over 100 GB/month
• Need analytics premium features
• Team collaboration required
• Commercial use of Hobby tier is technically not allowed per ToS

For personal blogs and small projects, Hobby free tier is sufficient long-term.

Reproduce this yourself

Everything in this guide is free to try:

1. Create an Astro site: npm create astro@latest
2. Push to GitHub
3. Import to Vercel
4. Total time: 15 minutes to live site

Custom domain setup adds another 15-30 minutes (mostly waiting for DNS).

Bottom line

Deploying Astro to Vercel is the smoothest deploy experience in 2026. Auto-detects framework, handles SSL, provides preview deployments, and free tier fits most projects.

Steps:

1. Push code to GitHub
2. Import repo in Vercel
3. Wait 60 seconds
4. Site live

Custom domain: add DNS records, wait for propagation.

That’s the entire deployment story for a modern static site.