Skip to main content
The @astrojs/vercel adapter enables your Astro project to deploy on Vercel with full SSR (Server-Side Rendering) and edge capabilities.

​
Installation

The adapter is already included in this boilerplate. To install it in a new project: 
npm install @astrojs/vercel

bun add @astrojs/vercel

​
Required Dependencies

From package.json, the key dependencies are:
package.json
{
  "dependencies": {
    "@astrojs/vercel": "^9.0.4",
    "@vercel/analytics": "^1.6.1",
    "@vercel/speed-insights": "^1.3.1",
    "astro": "^5.16.11"
  }
}

​
Basic Configuration

The adapter is configured in astro.config.mjs. Here’s the complete configuration from this boilerplate:
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,
      bypassToken: '115556d774a8115556d774a8115556d774a8s',
      exclude: ['/api/revalidate', '/ssr', '/edge.json'],
    },
  }),
})

​
Configuration Options

​
Output Mode

​
output
string
required
Set to 'server' to enable SSR (Server-Side Rendering) for your entire site.
output: 'server'
Individual pages can opt-in to static rendering by setting export const prerender = true in the page frontmatter.

​
Edge Middleware

​
edgeMiddleware
boolean
default:"false"
Enables edge middleware support for running code on Vercel’s Edge Network.
edgeMiddleware: true
When enabled, your src/middleware.ts file will run on the edge, allowing you to:
  • Intercept requests before they reach your pages
  • Modify responses
  • Add custom headers
  • Implement authentication logic

​
Image Service

​
imageService
boolean
default:"false"
Enables Vercel’s Image Optimization service for automatic image processing.
imageService: true

​
Images Configuration

​
imagesConfig.sizes
number[]
Array of image widths to generate. These should match your responsive breakpoints.
sizes: [320, 640, 1280]
​
imagesConfig.domains
string[]
Allowed external domains for image optimization. Leave empty to allow all domains.
domains: []
​
imagesConfig.remotePatterns
object[]
Fine-grained control over allowed remote image sources using pattern matching.
remotePatterns: [
  {
    protocol: 'https',
    hostname: '^via\\.placeholder\\.com$',
    pathname: '^/1280x640/.*$',
  },
]
Use regex patterns for hostname and pathname to match specific URLs.

​
Web Analytics

​
webAnalytics.enabled
boolean
default:"false"
Enables Vercel Web Analytics for tracking page views and performance metrics.
webAnalytics: {
  enabled: true,
}
This requires Vercel Web Analytics to be enabled in your Vercel project settings.

​
Incremental Static Regeneration (ISR)

ISR allows you to update static pages without rebuilding your entire site.
​
isr
boolean | object
Enable ISR with true for default settings, or use an object for advanced configuration.
// Simple enable
isr: true

// Advanced configuration
isr: {
  expiration: 60 * 60 * 24,
  bypassToken: 'your-secret-token',
  exclude: ['/api/*', '/ssr'],
}
​
isr.expiration
number
Time in seconds before a page is regenerated. Default is 1 day (86400 seconds).
expiration: 60 * 60 * 24 // 24 hours
​
isr.bypassToken
string
A secret token to bypass the cache and force regeneration.
bypassToken: '115556d774a8115556d774a8115556d774a8s'
Keep this token secret! Anyone with this token can force cache invalidation.
Use it in a URL like:
https://your-site.com/page?__prerender_bypass=your-token
​
isr.exclude
string[]
Routes that should always be served fresh (never cached).
exclude: ['/api/revalidate', '/ssr', '/edge.json']

​
Development vs Production

During development, you can use a different image service:
adapter: vercel({
  devImageService: 'squoosh',
  imageService: true,
})
This uses the lighter Squoosh service locally while Vercel’s optimization is used in production.

​
Example: Page with ISR

To use ISR on a specific page:
src/pages/isr.astro
---
export const prerender = true // Enable static generation for ISR

const data = await fetch('https://api.example.com/data')
const content = await data.json()
---

<Layout>
  <h1>This page uses ISR</h1>
  <p>Content will refresh every 24 hours</p>
  {/* Use your data here */}
</Layout>

​
Vercel CLI Scripts

The boilerplate includes helpful Vercel CLI commands:
package.json
{
  "scripts": {
    "vercel:dev": "vercel dev",
    "vercel:link": "vercel link"
  }
}
  • vercel:dev - Run the project locally with Vercel’s development environment
  • vercel:link - Link your local project to a Vercel project
Install the Vercel CLI globally with npm i -g vercel to use these commands.

Build docs developers (and LLMs) love

Get started for freeTalk to us