What will I learn from this astro-integrations tutorial?

Step-by-step guide to integrating Vercel with your Astro website. Installation, configuration, and best practices. This comprehensive guide covers all the essential concepts and practical steps you need to master astro-integrations.

Is this astro-integrations tutorial suitable for beginners?

This tutorial is designed to be accessible for learners at various skill levels. We provide clear explanations and step-by-step instructions to help you understand astro-integrations concepts effectively.

How long does it take to complete this astro-integrations tutorial?

This tutorial has an estimated reading time of 4 minutes. However, we recommend taking additional time to practice the concepts and techniques covered to fully master the material.

Where can I find more astro-integrations tutorials and resources?

You can find more astro-integrations tutorials in our astro-integrations category section. We also recommend exploring our related articles and following our blog for the latest updates on astro-integrations techniques and best practices.

/ astro-integrations / How to Use Vercel with Astro: Complete Guide

astro-integrations • February 17, 2026 • 4 min read

How to Use Vercel with Astro: Complete Guide

Step-by-step guide to integrating Vercel with your Astro website. Installation, configuration, and best practices.

Vercel is one of the best places to deploy an Astro site, especially when you need server-side rendering alongside static pages. Astro has an official Vercel adapter that handles everything from serverless functions to edge rendering. The deploy experience is basically zero-config once the adapter is set up.

Prerequisites

Node.js 18+
An Astro project (npm create astro@latest)
A Vercel account (free tier at vercel.com)
Your project in a Git repository (GitHub, GitLab, or Bitbucket)

Installation

Add the official Vercel adapter:

npx astro add vercel

This command installs @astrojs/vercel and updates your Astro config automatically.

Configuration

After running the add command, your config should look like this:

// astro.config.mjs
import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel";

export default defineConfig({
  output: "hybrid",
  adapter: vercel(),
});

The hybrid output mode means pages are static by default, and you opt into server-side rendering on a per-page basis using export const prerender = false.

For a fully static site, use output: "static" and you do not need the adapter at all. Just push to Vercel and it will build and serve your static files.

Basic Usage

With the adapter in place, you can mix static and dynamic pages. Static pages get pre-rendered at build time, and server-rendered pages run as Vercel Serverless Functions.

---
// src/pages/dashboard.astro
// This page renders on every request
export const prerender = false;

const user = await getUser(Astro.cookies.get("token")?.value);
---

<html>
  <body>
    <h1>Welcome, {user?.name || "Guest"}</h1>
  </body>
</html>

Static pages (the default in hybrid mode) just work normally:

---
// src/pages/about.astro
// This page is pre-rendered at build time (default behavior)
---

<html>
  <body>
    <h1>About Us</h1>
    <p>This page is static and loads instantly.</p>
  </body>
</html>

Environment Variables

Set your environment variables in the Vercel dashboard under Settings > Environment Variables. In your Astro code, access them with import.meta.env:

// Server-side only (API routes, SSR pages)
const apiKey = import.meta.env.API_SECRET_KEY;

// Client-side accessible (prefix with PUBLIC_)
const siteUrl = import.meta.env.PUBLIC_SITE_URL;

API Routes

Vercel automatically turns Astro API routes into serverless functions:

// src/pages/api/hello.ts
import type { APIRoute } from "astro";

export const GET: APIRoute = async () => {
  return new Response(JSON.stringify({ message: "Hello from Vercel!" }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
};

Edge Rendering

For pages that need to run at the edge (lower latency, closer to users), you can configure the adapter:

// astro.config.mjs
import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel";

export default defineConfig({
  output: "hybrid",
  adapter: vercel({
    edgeMiddleware: true,
  }),
});

Production Tips

Use ISR for semi-dynamic content. Incremental Static Regeneration lets you serve cached static pages while revalidating in the background. Great for content that updates occasionally.
Set proper cache headers. For API routes, set Cache-Control headers. Vercel's Edge Network respects these and will cache responses accordingly.
Use Vercel Analytics. Enable Web Analytics and Speed Insights in your Vercel dashboard for free Core Web Vitals monitoring. No code changes needed.
Preview deployments for every PR. Vercel creates a unique preview URL for every pull request. Use this to test changes before merging to production.
Keep functions small. Each server-rendered page becomes a serverless function. Avoid importing heavy dependencies in SSR pages to keep cold starts fast.

Alternatives to Consider

Cloudflare Pages if you want unlimited bandwidth on the free tier and a global edge network. Also has an official Astro adapter.
Netlify if you prefer their form handling, identity, and build plugin ecosystem. Very similar to Vercel for Astro.
AWS Amplify if you are already invested in the AWS ecosystem and need deeper integration with AWS services.

Wrapping Up

Vercel and Astro are a natural fit. The official adapter handles the deployment plumbing, hybrid rendering gives you the flexibility to mix static and dynamic, and Vercel's infrastructure handles the rest. Push your code and it just works.