Deploying to Vercel

Vercel is WP2Astro's integrated deployment platform, offering seamless hosting for your Astro sites with automatic builds, global CDN, and zero configuration required.

Why Vercel?

WP2Astro integrates directly with Vercel because:

• ✅ Automatic Deploys: Every push triggers a new deployment
• ✅ Global CDN: Serve from 100+ edge locations worldwide
• ✅ Zero Config: Detects Astro automatically
• ✅ Fast Builds: Optimized build infrastructure
• ✅ Free Tier: Generous limits for personal projects
• ✅ Custom Domains: Easy SSL and DNS management
• ✅ Preview Deployments: Test before going live

[screenshot of Vercel connection modal]

Setting Up Vercel

Step 1: Connect Vercel Account

From your WP2Astro dashboard:

1. Look for the "Deploy to Vercel" section in the sidebar
2. Click "Connect Vercel"
3. You'll see a modal with two options:

Option A: Connect with Vercel OAuth

• Click "Connect Vercel Account"
• Authorize WP2Astro in Vercel popup
• Instant setup, easiest method

Option B: Use Vercel Token

• Get token from vercel.com/account/tokens
• Click "Create Token"
• Name it "WP2Astro"
• Copy the token
• Paste into WP2Astro modal
• Click "Connect"

Step 2: Setup Project Deployment

Once Vercel is connected:

1. Find your project card on the dashboard
2. Click "Setup Deployment" button
3. A modal opens showing your project details
4. Click "Deploy to Vercel"

What Happens Next

WP2Astro automatically:

This takes about 2-3 minutes.

[screenshot of deployment status]

Deployment Status

Monitoring Deployments

Your project card shows real-time status:

Building 🟡

• Vercel is compiling your site
• Installing dependencies
• Running npm run build
• Optimizing assets

Live ✅

• Successfully deployed
• Site is accessible
• Click "View Site" to open
• URL: https://your-project.vercel.app

Failed ❌

• Build encountered an error
• Check logs in Vercel dashboard
• Fix the issue and redeploy

[screenshot of deployment status]

Refresh Status

If status seems stuck:

1. Click the refresh icon ⟳ on your project card
2. Status updates immediately
3. Fetches latest deployment info from Vercel

Automatic Deployments

After initial setup, deployments happen automatically.

How Auto-Deploy Works

Timeline

• Save: Instant (auto-save)
• Commit: 1-2 seconds
• Build trigger: 5-10 seconds
• Build time: 1-2 minutes
• Deploy: 10-20 seconds
• Total: ~2-3 minutes from save to live

What Triggers Deployment

Deployments are triggered by:

• Saving files in the IDE
• Pushing commits via terminal
• Merging pull requests
• Manual deploy from Vercel dashboard

Build Configuration

Vercel automatically detects Astro projects and configures everything:

Auto-Detected Settings

Framework: Astro
Build Command: npm run build
Output Directory: dist
Install Command: npm install
Node.js Version: 20.x

You don't need to configure anything - it just works!

Custom Build Settings (Advanced)

If you need to customize, create vercel.json:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "devCommand": "npm run dev",
  "installCommand": "npm install",
  "framework": "astro"
}

Environment Variables

Add secrets via Vercel dashboard:

1. Go to Project Settings in Vercel
2. Click "Environment Variables"
3. Add variables:

Access in your code:

const siteUrl = import.meta.env.SITE_URL;
const apiUrl = import.meta.env.PUBLIC_API_URL;

Understanding the Deployment

What Gets Deployed

When Vercel builds your site:

Build Output

Vercel generates:

Optimizations Applied

Vercel automatically:

• Compresses all assets (Gzip/Brotli)
• Optimizes images (WebP, AVIF)
• Minifies CSS and JavaScript
• Generates source maps
• Creates service worker (if configured)
• Sets cache headers

Custom Domains

Adding Your Domain

1. Go to Vercel dashboard
2. Select your project
3. Go to Settings → Domains
4. Click "Add Domain"
5. Enter your domain (e.g., yoursite.com)

DNS Configuration

For apex domain (yoursite.com):

For www subdomain:

SSL Certificate

Vercel automatically:

• Provisions SSL certificate
• Renews before expiration
• Redirects HTTP to HTTPS
• Supports custom certificates

No configuration needed! SSL just works.

Deployment URLs

Default URL

Every project gets a free Vercel URL:

Preview URLs

Every deployment gets unique URL:

Use preview URLs to:

• Test before going live
• Share with clients
• QA different branches

Production URL

Your main deployment URL:

Always points to latest successful deployment.

Deployment Logs

Viewing Build Logs

From Vercel dashboard:

1. Go to your project
2. Click "Deployments" tab
3. Click specific deployment
4. View detailed logs

Log Contents

[12:34:56] Installing dependencies...
[12:35:12] npm install completed
[12:35:13] Running build command...
[12:35:14] > astro build
[12:35:15] Building for production...
[12:36:42] Build completed
[12:36:43] Deploying to CDN...
[12:36:55] Deployment complete!

Debug Build Issues

Common errors and solutions:

Module Not Found:

Error: Cannot find module 'package-name'
Fix: npm install package-name

Build Timeout:

Error: Build exceeded maximum duration
Fix: Optimize build, upgrade plan

Out of Memory:

Error: JavaScript heap out of memory
Fix: Reduce build size, upgrade plan

Performance

Global CDN

Your site is deployed to Vercel's edge network:

• 100+ locations worldwide
• Automatic routing to nearest server
• DDoS protection included
• 99.99% uptime SLA

Speed Metrics

Typical performance for Astro + Vercel:

• TTFB: < 50ms (Time To First Byte)
• FCP: < 1s (First Contentful Paint)
• LCP: < 1.5s (Largest Contentful Paint)
• TTI: < 2s (Time To Interactive)

Lighthouse Scores: Often 95-100 across all metrics

Caching Strategy

Vercel automatically sets optimal cache headers:

Free Tier Limits

Vercel's Hobby (free) plan includes:

Bandwidth:

• 100 GB per month
• Enough for 100,000+ page views

Build Time:

• 100 hours per month
• ~6,000 builds
• 1 minute average build = plenty of headroom

Deployments:

• Unlimited deployments
• Unlimited preview deployments

Projects:

• Unlimited projects

Team Members:

• Solo developer (1 member)

Perfect for:

• Personal blogs
• Portfolio sites
• Side projects
• Small business sites

When to Upgrade

Consider Pro plan ($20/month) if you need:

• Commercial projects
• Team collaboration
• More bandwidth (1 TB)
• Faster builds
• Priority support
• Analytics
• Password protection

Rollback and Revert

Instant Rollback

Made a mistake? Rollback instantly:

1. Go to Vercel dashboard
2. Click "Deployments"
3. Find previous working deployment
4. Click "Promote to Production"
5. Previous version goes live immediately

How Rollback Works

No rebuild needed - previous version is cached.

Preview Deployments

Every Commit Gets a Preview

When you push to a branch:

Preview URLs

Use for:

• Testing new features
• Client review
• QA before merge
• Sharing with team

Disconnecting Vercel

Need to disconnect? From WP2Astro dashboard:

1. Go to sidebar
2. Find "Deploy to Vercel" section
3. Click "Disconnect Vercel"
4. Confirm disconnection

What happens:

• Vercel token removed from WP2Astro
• Project stays live on Vercel
• Deployments stop from WP2Astro
• Can reconnect anytime

Note: Your site continues running on Vercel. This only removes the WP2Astro connection.

Troubleshooting

Deployment Fails

Check build logs:

1. Go to Vercel dashboard
2. View deployment details
3. Look for error message
4. Fix the issue
5. Retry deployment

Common issues:

• Missing dependencies in package.json
• TypeScript errors
• Build script errors
• Environment variables not set

Site Not Updating

Possible causes:

1. Build failed - Check Vercel dashboard
2. Browser cache - Hard refresh (Cmd+Shift+R)
3. CDN cache - Wait 1-2 minutes
4. Not deployed - Check deployment status

Solutions:

• Clear browser cache
• Check deployment succeeded
• Verify changes committed to GitHub
• Check Vercel isn't paused

Wrong Version Deployed

If wrong version is live:

1. Check which commit is deployed (Vercel dashboard)
2. Verify correct code is on main branch
3. Trigger manual deploy from Vercel
4. Check deployment logs

Connection Issues

If can't connect Vercel:

1. Verify Vercel token is valid
2. Check Vercel account isn't suspended
3. Try disconnecting and reconnecting
4. Generate new token and try again

Best Practices

Deployment Workflow

Development:

For larger changes:

Testing Before Deploy

Local preview (optional):

# In IDE terminal
npm run build
npm run preview

Use preview deployments:

• Work on branches
• Get preview URLs
• Test thoroughly
• Merge when ready

Performance Monitoring

Use Vercel Analytics:

• See real user metrics
• Track Core Web Vitals
• Monitor performance
• Get insights

External tools:

• Google PageSpeed Insights
• GTmetrix
• WebPageTest

Advanced Features

Edge Functions

Add server-side functionality:

// api/hello.js
export default function handler(request) {
  return new Response(JSON.stringify({ 
    message: 'Hello from the edge!' 
  }), {
    headers: { 'content-type': 'application/json' }
  });
}

Redirects

Configure in vercel.json:

{
  "redirects": [
    {
      "source": "/old-blog/:slug",
      "destination": "/blog/:slug",
      "permanent": true
    }
  ]
}

Headers

Custom HTTP headers:

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        }
      ]
    }
  ]
}

Comparison: Vercel vs Others

Why Not Netlify or Cloudflare?

WP2Astro currently only supports Vercel because:

• Tight integration: Built specifically for WP2Astro
• Automatic setup: Zero configuration needed
• Best performance: Optimized for Astro
• Reliability: 99.99% uptime

Other platforms coming soon! We're working on:

• Netlify integration
• Cloudflare Pages support
• Self-hosted options

For now, Vercel provides the best experience with WP2Astro.

Next Steps

Now that your site is deployed:

• Add a custom domain
• Set up analytics
• Configure environment variables
• Learn about performance optimization

Additional Resources

• Vercel Documentation
• Astro on Vercel
• Vercel Community
• WP2Astro Support