Astro on Vercel

Astro is an all-in-one web framework that enables you to build performant static websites. People choose Astro when they want to build content-rich experiences with as little JavaScript as possible.

There are multiple ways to get started with Astro on Vercel:

• Choose a template from the Vercel templates marketplace
• If you already have a project with Astro, install Vercel CLI and run the vercel command from your project's root directory
• Clone one of our Astro example repos to your favorite git provider and deploy it on Vercel with the button below:

Deploy our Astro template, or view a live example.

DeployLive Example

Vercel deployments can integrate with your git provider to generate preview URLs for each pull request you make to your Astro project.

You can also use Astro in our Edge Runtime with our Astro at the Edge example project.

You can deploy a static Astro site to Vercel with zero configuration using our framework preset. To use many of Vercel's features, you must deploy your site using SSR. The recommended way to do this is with Astro's Vercel adapter.

The following steps will guide you through configuring the Vercel adapter in your Astro project.

pnpm astro add @astro/vercel

pnpm i @astro/vercel

import { defineConfig } from 'astro/config';
import vercelEdge from '@astrojs/vercel/edge';
 
export default defineConfig({
  output: 'server',
  adapter: vercelEdge(),
});

Server-Side Rendering (SSR) allows you to render pages dynamically on the server. This is useful for pages where the rendered data needs to be unique on every request. For example, verifying authentication or checking the geolocation of an incoming request.

Vercel offers SSR that scales down resource consumption when traffic is low, and scales up with traffic surges. This protects your site from accruing costs during periods of no traffic or losing business during high-traffic periods.

Enabling SSR for your Astro project allows you to use Edge and Serverless Functions with Vercel. This allows you to add dynamic elements to your app, such as user logins and personalized content.

Enable SSR by adding output: 'server' to your project's defineConfig object and installing the Vercel adapter. The following is an example of an astro.config.mjs file that enables Serverless SSR with the Vercel adapter.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
 
export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

To summarize, SSR with Astro on Vercel:

Deploying your Astro site to Vercel with SSR on either our Edge or Node.js serverless runtimes allows you to respond to requests dynamically at scale. The Node.js serverless runtime grants you a Node.js environment with enough compute power for complex tasks, while Edge grants you a limited environment with low latency.

You can use our Function Comparison table to decide which runtime is best for you. Edge Functions are generally faster than Serverless Functions when handling requests that require little processing power and rely on few or no databases. Serverless Functions are slower, but have more computational resources and full access to the Node.js API, which Edge Functions currently lack.

Serverless Functions may also be faster than Edge Functions for requests that rely on databases. See our docs on Regional Function Execution to learn more.

When you create an Astro page with a slug in brackets, such as [post] or [author], you can generate pages based on the value in the slug's position when a user visits a route.

For example, a page like posts/[post].astro can dynamically render a different post when a user visits your-site.com/posts/example-1 or your-site.com/posts/example-2.

---
const { post } = Astro.params;
---
<h1>{post}</h1>
<p>
  ... Other content here
</p>

Once you install Astro's Vercel adapter and configure your astro.config.mjs to use either Serverless or Edge, all routes in your site will be server-rendered on your chosen runtime by default.

Use the tabs below to see an example astro.config.mjs that use Server-Side Rendering in Vercel's Edge or Serverless runtime:

With your config file setup, you can use Astro's component script to get the route segments, and render content dynamically based on which path the user is visiting.

The following example renders an Astro page dynamically. If the user is visiting an unexpected path, it redirects them to a 404 page.

---
const pages = [
  {
    slug: 'products',
    title: 'Astro products',
    text: 'We have lots of products for you',
  },
  {
    slug: 'products/astro-handbook',
    title: 'The ultimate Astro handbook',
    text: 'If you want to learn Astro, you must read this book.',
  }
];
 
const { slug } = Astro.params;
const page = pages.find((page) => page.slug === slug);
if (!page) return Astro.redirect("/404");
const { title, text } = page;
---
<html>
<head>
  <title>{title}</title>
</head>
<body>
  <h1>{title}</h1>
  <p>{text}</p>
</body>
</html>

You can also create Edge or Serverless Functions by creating a /api directory in your project's root directory.

The following is an example of a basic Edge Function:

export const config = {
  runtime: 'edge',
};
 
export default (req: Request) => {
  return new Response(`Hello, from ${req.url} I'm now an Edge Function!`);
};

To learn more, see our:

• Edge Functions quickstart guide
• Serverless Functions quickstart guide

To summarize, Edge Functions with Astro on Vercel:

Astro does not support route-specific middleware. Instead, you can create a single global middleware.js file, which will run before every request.

To limit the code in your middleware.js module to specific routes, you can export a config object with the matcher property, which allows you to specify which paths the middleware should apply to. You can set the value of the matcher to a plain string, or a string containing regex.

The following is an example of a middleware.js file that matches the /admin path and redirects to a path called /redirected.

export const config = {
  // Only run the middleware on the admin route
  matcher: '/admin',
};
 
export default function middleware(request: Request): Response {
  const url = new URL(request.url);
 
  if (url.pathname === '/admin') {
    url.pathname = '/redirected';
  }
  return Response.redirect(url);
}

Learn more about matcher in our Middleware docs.

You can also configure your Astro site to run on either the Edge or Node.js serverless runtime, allowing you to use middleware with Edge or Serverless functions. Using matcher does not alter the runtime your API routes execute in. You cannot use matcher to deploy certain API routes in one runtime and others in another. Your chosen runtime applies to all API routes.

The Response your middleware function sends back to Astro is an instance of the Web Fetch API's Response interface. Learn more about Response objects in the MDN docs.

You can return a new Response() object with the information you want to send, or use the static methods redirect and error to redirect users or send an internal server error response via middleware.

The following is an example of a middleware.js file that matches the /admin path and responds with a 404.

export const config = {
  // Only run the middleware on the admin route
  matcher: '/admin',
};
 
export default function middleware(request: Request): Response {
  const url = new URL(request.url);
 
  if (url.pathname === '/admin') {
    url.pathname = '/redirected';
  }
  return new Response(null, {
    status: 404,
    statusText: 'Not found',
  });
}

You can test Middleware in your local environment with Vercel CLI. The vercel dev or vc dev commands add some helpers to your framework's standard dev equivalent command, extending it to let you also test Vercel features like Middleware and Serverless Functions.

Install Vercel CLI with the following terminal command:

pnpm i -g vercel

To summarize, Edge Middleware with Astro on Vercel:

We do not recommend using vercel.json to rewrite URL paths with astro projects. At the moment, trying to rewrite a URL with vercel.json produces inconsistent behavior, and is not officially supported. Read our docs on Edge Middleware with Astro to learn how to execute redirects from Middleware instead.

See our Frameworks documentation page to learn about the benefits available to all frameworks when you deploy on Vercel.

Learn more about deploying Astro projects on Vercel with the following resources: