Docs/Deploying to Vercel

Deploying to Vercel

Deploy your Astro site to Vercel with automatic builds.

Deploying to Vercel

Vercel is the recommended hosting platform for PhantomWP sites. It offers free hosting, automatic HTTPS, global CDN, and seamless GitHub integration.

Why Vercel?

  • Free tier - Perfect for personal and small business sites
  • Automatic deploys - Every push to GitHub triggers a new build
  • Global CDN - Your site loads fast worldwide
  • Preview deployments - Every branch gets its own preview URL
  • Custom domains - Use your own domain for free
  • Analytics - Built-in web analytics (paid feature)

Connecting Vercel

Step 1: Get a Vercel Token

  1. Go to vercel.com and sign in (or create an account)
  2. Click your profile picture → Settings
  3. Go to Tokens in the sidebar
  4. Click Create Token
  5. Name it "PhantomWP" and select an expiration
  6. Copy the token (you won't see it again!)

Step 2: Connect in PhantomWP

  1. Go to your PhantomWP Dashboard
  2. Find your project
  3. Click Setup Deployment (or the Vercel icon if already connected)
  4. Paste your Vercel token
  5. Click Connect

Vercel setup

Step 3: Import Your Repository

After connecting, PhantomWP guides you through importing:

  1. Select the GitHub repository
  2. Choose your Vercel team (or personal account)
  3. Configure project settings (usually defaults work fine)
  4. Click Deploy

Your first deployment starts immediately!

Deployment Settings

Project Name

By default, uses your repository name. You can change this in Vercel settings later.

Framework Preset

PhantomWP automatically selects "Astro" as the framework. This ensures proper build settings.

Build Settings

Default settings for Astro projects:

  • Build Command: npm run build
  • Output Directory: dist
  • Install Command: npm install

Usually you don't need to change these.

Environment Variables

If your site needs environment variables:

  1. Go to your project in Vercel
  2. Click Settings → Environment Variables
  3. Add your variables
  4. Redeploy for changes to take effect

Automatic Deployments

Once connected, every push to GitHub triggers a deployment. Your changes only go live after you commit and push them.

Committing Your Changes

To deploy your changes:

  1. Make changes in the PhantomWP IDE
  2. Click the Git icon in the header bar
  3. Review your changed files
  4. Write a commit message describing your changes
  5. Click Commit & Push

Git commit dialog

💡

Changes are not deployed automatically as you edit. You must commit and push to trigger a deployment. This gives you control over when your site updates.

After pushing, Vercel automatically builds and deploys your site. Updates typically go live in 1-2 minutes.

Deployment Status

Check deployment status in:

  • PhantomWP Dashboard - Shows status badge on project card
  • Vercel Dashboard - Full deployment logs and history
  • GitHub - Deployment status on commits

Custom Domains

Adding a Custom Domain

  1. Go to your project in Vercel
  2. Click Settings → Domains
  3. Enter your domain (e.g., mysite.com)
  4. Follow DNS configuration instructions

DNS Configuration

Option A: Vercel Nameservers (Recommended) Point your domain's nameservers to Vercel:

  • ns1.vercel-dns.com
  • ns2.vercel-dns.com

Option B: A/CNAME Records Add these records at your DNS provider:

  • A Record: 76.76.21.21
  • CNAME: cname.vercel-dns.com

SSL/HTTPS

Vercel automatically provisions and renews SSL certificates. Your site is HTTPS-only with no configuration needed.

Deployment Logs

If a deployment fails, check the logs:

  1. Go to Vercel Dashboard
  2. Click on the failed deployment
  3. View Build Logs for details

Common issues:

  • Missing dependencies - Check package.json
  • Build errors - Check your Astro code for errors
  • Out of memory - Simplify build or upgrade Vercel plan

Rollbacks

If a deployment breaks your site:

  1. Go to Vercel Dashboard → Deployments
  2. Find the last working deployment
  3. Click ... → Promote to Production

Your site instantly reverts to the previous version.

Disconnecting Vercel

To disconnect Vercel from PhantomWP:

  1. Go to PhantomWP Dashboard
  2. Find the Vercel section in the sidebar
  3. Click Disconnect

This removes the connection but doesn't delete your Vercel project.

Vercel Limits (Free Tier)

The free tier includes:

  • 100 GB bandwidth/month
  • Unlimited static deployments
  • 1 concurrent build
  • Serverless functions (100 GB-hours/month)

Plenty for most personal and small business sites!

Alternative Hosts

PhantomWP sites work on any static host:

  • Netlify - Similar features to Vercel
  • Cloudflare Pages - Great performance, free tier
  • GitHub Pages - Free, good for simple sites
  • AWS S3 + CloudFront - Maximum control

For these platforms, build locally or use their GitHub integrations directly.

Troubleshooting

"You need to add a Login Connection to your GitHub account"

This error means your Vercel account is not connected to GitHub. Vercel needs GitHub access to pull your repository and set up automatic deployments.

To fix this:

  1. Go to Vercel Authentication Settings
  2. Connect your GitHub account under the authentication options
  3. Return to PhantomWP and try deploying again
⚠️

This is required even if you already have a Vercel API token. The token lets PhantomWP talk to Vercel, but Vercel itself still needs a GitHub connection to access your repository.

"Build Failed"

  1. Check build logs for specific errors
  2. Test locally: run npm run build in your codespace
  3. Fix any TypeScript or Astro errors

"Domain Not Working"

  1. Verify DNS records are correct
  2. Wait up to 48 hours for DNS propagation
  3. Check for conflicting records

"Site Shows Old Content"

  1. Clear your browser cache
  2. Wait for CDN cache to expire (~1 minute)
  3. Trigger a new deployment

"404 on Pages"

  1. Check that pages exist in src/pages/
  2. Verify dynamic routes are configured correctly
  3. Check astro.config.mjs for routing settings

Next Steps

Previous
Store Features
Next
WordPress Security