Skip to main content
Deploying your Astro Vercel Boilerplate to production is straightforward. Vercel automatically detects Astro projects and configures the build settings for you.

​
Deployment Methods

You can deploy your Astro site to Vercel using any of these methods:
1

Prerequisites

Before deploying, make sure you have:
  • A Vercel account (free tier available)
  • Your project pushed to a Git repository (GitHub, GitLab, or Bitbucket)
  • The Vercel CLI installed (optional, for CLI deployment)
If you don’t have a Git repository yet, initialize one and push your code:
git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repo-url>
git push -u origin main
2

Deploy via Vercel Dashboard

The easiest way to deploy is through the Vercel dashboard:
  1. Go to vercel.com/new
  2. Import your Git repository
  3. Vercel will automatically detect your Astro project
  4. Click Deploy
That’s it! Vercel will build and deploy your site automatically.
For the Astro Vercel Boilerplate, you can use the one-click deploy button:Deploy with Vercel
3

Deploy via Vercel CLI

For more control, use the Vercel CLI:
npm i -g vercel
The CLI will guide you through the setup process, including linking your project to a Vercel project.
When deploying for the first time, the CLI will ask you to configure your project. You can accept the defaults, as Vercel automatically detects the correct settings for Astro.
4

Configure environment variables (if needed)

If your project requires environment variables, add them in the Vercel dashboard:
  1. Go to your project settings
  2. Navigate to Environment Variables
  3. Add your variables for Production, Preview, and Development environments
The boilerplate doesn’t require environment variables by default, but you may need them for:
  • API keys
  • Database connections
  • Third-party service credentials
You can also set environment variables using the CLI:
vercel env add <variable-name>
5

Verify deployment

After deployment completes, Vercel will provide you with:
  • A production URL (e.g., your-project.vercel.app)
  • A preview URL for each Git branch
  • Automatic HTTPS certificates
Visit your production URL to verify the deployment. You should see:
  • Your homepage displaying IP address and city information
  • All demo pages functioning correctly
  • Vercel Analytics enabled (check the dashboard)
Each Git push to your main branch will trigger a new production deployment automatically. Pushes to other branches create preview deployments.

​
Astro Configuration for Vercel

The boilerplate is pre-configured with optimal Vercel settings in astro.config.mjs:
astro.config.mjs
import vercel from '@astrojs/vercel'
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astro-vercel-boilerplate.vercel.app',
  trailingSlash: 'never',
  output: 'server',
  adapter: vercel({
    edgeMiddleware: true,
    imageService: true,
    imagesConfig: {
      sizes: [320, 640, 1280],
      domains: [],
      remotePatterns: [
        {
          protocol: 'https',
        },
      ],
    },
    webAnalytics: {
      enabled: true,
    },
    isr: {
      expiration: 60 * 60 * 24, // 24 hours
      bypassToken: '115556d774a8115556d774a8115556d774a8s',
      exclude: ['/api/revalidate', '/ssr', '/edge.json'],
    },
  }),
})

​
Key Configuration Options

output: 'server' - Enables server-side rendering by default. Pages can opt into static pre-rendering using export const prerender = true.
edgeMiddleware: true - Runs middleware on Vercel Edge Functions for ultra-low latency request processing.
imageService: true - Enables Vercel Image Optimization for automatic image resizing and format conversion.
webAnalytics.enabled: true - Automatically enables Vercel Web Analytics for your site.
isr.expiration - Sets the cache duration for ISR pages. In this config, pages are cached for 24 hours.

​
ISR Configuration

Incremental Static Regeneration (ISR) is enabled with these settings: 
isr: {
  expiration: 60 * 60 * 24, // Cache for 24 hours
  bypassToken: '115556d774a8115556d774a8s', // Token for on-demand revalidation
  exclude: ['/api/revalidate', '/ssr', '/edge.json'], // Routes that should not use ISR
}
Make sure to change the bypassToken to a secure random string in production. This token is used for on-demand revalidation via the /api/revalidate endpoint.

​
Image Optimization

The boilerplate uses Vercel’s Image Optimization service with these settings: 
imagesConfig: {
  sizes: [320, 640, 1280], // Responsive image sizes
  domains: [],              // Allowed external domains
  remotePatterns: [
    {
      protocol: 'https',
    },
  ],
}
Example usage from the /image page:
src/pages/image.astro
---
import { Image as AstroImage } from 'astro:assets'
import imageDark from '@/assets/images/context-menu-dark.jpg'
import imageLight from '@/assets/images/context-menu-light.jpg'
import Layout from '@/layouts/Layout.astro'
---

<Layout seo={{ title: 'Image', description: 'Astro Asset using Vercel Image Optimization' }}>
  <section>
    <AstroImage
      src={imageLight}
      alt="Light Screenshot"
      width={imageLight.width}
      height={imageLight.height}
      format={'webp'}
      quality={80}
      class="light"
    />
  </section>
</Layout>

​
Monitoring Your Deployment

Once deployed, you can monitor your site using:
  • Vercel Analytics - Track page views, visitor metrics, and top pages
  • Speed Insights - Monitor Core Web Vitals and performance scores
  • Deployment logs - View build logs and runtime errors
  • Function logs - Debug edge functions and serverless functions
Access these from your Vercel dashboard under your project.

​
Continuous Deployment

Vercel automatically sets up continuous deployment:
  • Production deployments - Triggered on pushes to your main/master branch
  • Preview deployments - Created for every pull request and branch push
  • Automatic rollbacks - Instantly rollback to previous deployments if needed

​
Custom Domains

To add a custom domain:
  1. Go to your project settings in Vercel
  2. Navigate to Domains
  3. Add your custom domain
  4. Configure DNS records as instructed
Vercel automatically provisions SSL certificates for all domains.

​
Troubleshooting

​
Build Failures

If your build fails:
  1. Check the build logs in the Vercel dashboard
  2. Ensure all dependencies are listed in package.json
  3. Verify your astro.config.mjs is valid
  4. Run npm run build locally to reproduce the error

​
Runtime Errors

If you encounter runtime errors:
  1. Check the Function logs in Vercel
  2. Ensure environment variables are set correctly
  3. Verify edge function compatibility (some Node.js APIs are not available on the edge)

​
Next Steps

Vercel Documentation

Learn more about Astro on Vercel

Astro Vercel Adapter

Deep dive into the Vercel adapter

Build docs developers (and LLMs) love

Get started for freeTalk to us