Deploy to Vercel

What Is Vercel?

Vercel is a cloud platform for static sites and serverless functions. It is the company behind Next.js, and it provides a global edge network with automatic HTTPS, Git integration, and zero-configuration deployment for Astro projects .

For Astro Docus, Vercel is an excellent choice because:

• Zero configuration required for static Astro sites
• Automatic deployments on every Git push
• Preview deployments for every pull request
• Free Hobby plan suitable for personal projects
• Auto-detects Astro and configures the build settings correctly

This guide covers two methods:

1. GitHub Integration (recommended) — Vercel builds and deploys automatically
2. Vercel CLI — deploy directly from your local machine

---

Prerequisites

Before starting, you need:

• A Vercel account (free)
• Your Astro Docus project pushed to GitHub (see the previous guide)
• A terminal open in your project folder

---

Method 1 — Deploy via GitHub Integration

This is the recommended method. Once set up, every push to your main branch triggers an automatic production deploy.

Step 1 — Sign Up or Log In to Vercel

1. Go to: https://vercel.com/signup
2. Click Continue with GitHub
3. Authorize Vercel to access your GitHub account
4. Complete the onboarding flow

Using GitHub as your sign-in method simplifies the connection later.

Step 2 — Create a New Project

1. After logging in, you land on the Vercel dashboard
2. Click the Add New… button and select Project
3. You see a list of your GitHub repositories

Step 3 — Import Your Repository

1. Find your Astro Docus repository in the list
2. Click Import
3. Vercel now shows the project configuration screen

Step 4 — Configure the Project

Vercel auto-detects that this is an Astro project . The default settings are usually correct, but verify:

Setting	Value
Framework Preset	Astro (auto-detected)
Build Command	npm run build
Output Directory	dist
Install Command	npm install

If these match, you do not need to change anything.

Step 5 — Deploy

1. Click Deploy
2. Vercel begins building your site
3. You see a build log with each step
4. First build takes 1–3 minutes
5. When complete, you see a success screen with your live URL

Step 6 — Your Live Site

After deployment, you receive a unique URL:

https://astrodocus.vercel.app

Open this URL in your browser. Your Astro Docus site is now live.

Automatic Deployments

Once connected, every push to your repository triggers:

Action	Result
Push to main	Production deploy
Push to another branch	Preview deploy with unique URL
Open a pull request	Preview deploy with PR comment

This means you never manually deploy again. Just git push, and Vercel handles the rest.

---

Method 2 — Deploy via Vercel CLI

Use this method if you prefer to deploy from the command line or if your project is not connected to GitHub.

Step 1 — Install Vercel CLI

npm install -g vercel

Verify installation:

vercel --version

Step 2 — Log In to Vercel

vercel login

This opens your browser. Log in to Vercel and authorize the CLI .

Step 3 — Deploy

Navigate to your project folder and run:

vercel

The CLI detects Astro, builds your project, and deploys it .

When prompted “Want to override the settings?” choose N (No) .

Step 4 — Deploy to Production

The first vercel command creates a preview deployment. To deploy to production:

vercel --prod

This assigns the deployment to your production domain .

Step 5 — Your Live Site

After deployment, the CLI outputs your live URL:

https://astrodocus.vercel.app

Deploying Updates Later

Every time you want to update the live site:

vercel --prod

Or for a preview first:

vercel
vercel --prod

---

Adding a Custom Domain

A *.vercel.app subdomain works, but a custom domain looks more professional.

Step 1 — Go to Your Project

1. In the Vercel dashboard, click your project
2. Go to the Settings tab
3. Click Domains in the sidebar

Step 2 — Add Domain

1. Enter your domain (e.g., docs.yourdomain.com)
2. Click Add

Step 3 — Configure DNS

Vercel shows you the required DNS records. Go to your domain registrar (Namecheap, GoDaddy, Cloudflare, etc.) and add:

• A record pointing to Vercel’s IP (for root domain)
• CNAME record pointing to cname.vercel-dns.com (for subdomains)

Step 4 — Verify

After DNS propagates (usually minutes, sometimes hours), your custom domain works with HTTPS automatically .

---

Vercel Free Tier Limits

The Hobby plan is free and sufficient for most personal projects :

Resource	Included
Bandwidth	100 GB/month
Fast Origin Transfer	10 GB
Edge Requests	1,000,000/month
Build Minutes	6,000/month
Image Transformations	5,000/month
Deployments	Unlimited
Team Members	1

The Hobby plan is for non-commercial, personal use only . If you exceed limits, your project is paused until the next 30-day cycle.

---

Astro Configuration for Vercel

Astro Docus ships as a static site, which means no adapter is required for Vercel .

If you want to use Vercel-specific features (Image Optimization, Web Analytics, Server-Side Rendering), install the Vercel adapter:

npx astro add vercel

This updates astro.config.mjs automatically . For a static Astro Docus site, this is not necessary.

---

Troubleshooting

Problem	Likely Cause	Fix
Build fails	Wrong Node version	Set NODE_VERSION environment variable
404 errors	Wrong output directory	Verify dist is set
Site works locally but not on Vercel	Missing site URL	Set site in astro.config.mjs
CLI authentication fails	Token expired	Run vercel login again
Custom domain not working	DNS not propagated	Wait, or check DNS records

---

Environment Variables (Optional)

If your project needs environment variables, set them in:

Vercel Dashboard → Your Project → Settings → Environment Variables

Or via CLI:

vercel env add VARIABLE_NAME

Common variables for Astro Docus:

Variable	Value	Purpose
NODE_VERSION	20	Ensures correct Node.js version
PUBLIC_SITE_URL	https://yourdomain.com	Canonical URL

---

Quick Recap

Method 1 — GitHub Integration (recommended):
1. Sign up at vercel.com with GitHub
2. Add New → Project
3. Import your Astro Docus repository
4. Verify settings (auto-detected)
5. Click Deploy
6. Live at *.vercel.app

Method 2 — Vercel CLI:
1. npm install -g vercel
2. vercel login
3. vercel (preview)
4. vercel --prod (production)
5. Live at *.vercel.app

Custom Domain:
- Dashboard → Project → Settings → Domains
- Add domain → Configure DNS
- HTTPS automatic

Free Tier:
- 100 GB bandwidth/month
- 6,000 build minutes/month
- Unlimited deployments

Vercel is zero-config for Astro static sites. Once connected to GitHub, every git push deploys your site globally with preview URLs for every pull request.

👉 Next: docs/deploy-hosting/netlify.md — deploy to Netlify.