Astro’s static export isn’t just pre-rendering; it’s a fundamental architectural choice that can make your entire application behave like a static site, even when you’re serving dynamic content.
Let’s see Astro and Vercel in action.
Imagine you’ve got an Astro site, my-astro-site, deployed on Vercel. Your astro.config.mjs looks like this:
import { defineConfig } from 'astro/config';
export default defineConfig({
// Default is 'static'
// output: 'static',
// For SSR:
// output: 'server',
// adapter: vercel()
});
And in your src/pages/index.astro you have:
---
const response = await fetch('https://api.github.com/users/astrodotbuild');
const data = await response.json();
---
<h1>Hello from Astro on Vercel!</h1>
<p>Astro's GitHub Stars: {data.stargazers_count}</p>
When you run vercel --prod in your local terminal, Vercel analyzes your astro.config.mjs.
If output is static (the default), Astro builds all your pages into plain HTML, CSS, and JS files. Vercel then deploys these static assets directly to its global CDN. When a user requests a page, they get a file from the nearest CDN edge, lightning fast. The fetch call in index.astro will not run at request time; it ran during the build process, and its result is embedded in the static HTML.
If you change your astro.config.mjs to:
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/server'; // Import the Vercel server adapter
export default defineConfig({
output: 'server',
adapter: vercel()
});
And run vercel --prod again, Vercel now sees the @astrojs/vercel/server adapter. Astro doesn’t just build static files; it builds a Node.js serverless function. Vercel deploys this function to its Edge Network. When a user requests index.astro, the request hits the Vercel Edge, which then executes your Astro serverless function. This function runs the fetch call in real-time for that specific request, gets the data, and then renders the index.astro component dynamically to HTML before sending it back to the user.
The core problem Astro solves here is the "JavaScript Everywhere" dilemma. You can write dynamic, interactive UIs using client-side JavaScript frameworks (React, Vue, Svelte, etc.) but Astro’s Islands Architecture allows you to ship zero JavaScript by default. Only the interactive components you explicitly mark as "client-side" will have their JavaScript sent to the browser. For everything else, Astro renders it on the server (during build for static, or at request time for SSR) and sends plain HTML. This drastically reduces load times and improves SEO, especially for content-heavy sites.
The output setting in astro.config.mjs dictates the fundamental deployment strategy. static means build-time pre-rendering into pure assets. server means leveraging server-side rendering (SSR) or Incremental Static Regeneration (ISR) capabilities through an adapter like @astrojs/vercel/server. The adapter is crucial because it translates Astro’s SSR output into a format Vercel’s infrastructure understands – typically a serverless function.
When you use the @astrojs/vercel/server adapter, Astro’s build process generates a single serverless function file (often in .vercel/output/functions/entry.func/) that Vercel deploys. This function encapsulates your entire server-side logic, including any API routes you define within Astro. Vercel then intelligently routes incoming requests to this function based on your astro.config.mjs and routing rules.
The surprising thing about Astro’s server output on Vercel is how it blurs the lines between static and dynamic. Even when configured for output: 'server', Astro can still leverage Vercel’s ISR capabilities. If a page is requested, and its data hasn’t changed since the last build or a specified revalidation period, Vercel can serve a cached static version. Only when the data needs to be fresh, or the cache expires, will the serverless function execute to fetch new data and re-render. This means you get the speed of static for unchanging content and the dynamism of SSR for content that requires real-time updates, all within a single Astro project.
The next step is understanding how to manage different output modes for different parts of your application, or how to integrate Vercel’s advanced features like Edge Functions with Astro.