Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท SSR, Adapters and Endpoints

Astro Output Modes, Prerendering and Adapters

Understand Astro's static and server output, opt pages in or out of prerendering, pick an adapter (Node, Vercel, Netlify, Cloudflare) and use server islands.

By default an Astro site is static: astro build renders every page to an HTML file once, and any file host can serve the result. That is the fastest and cheapest way to run a website. Sometimes, though, a page needs data that only exists at request time: the logged-in user, a cart, search results, a live price. For that, Astro supports server-side rendering (SSR), where a server runs your page code for each request.

This lesson explains the modes, the prerender switch, adapters, and how to keep most of a page static while one part stays dynamic.

Static versus server

Static Server (SSR)
When HTML is made At build time At request time
Hosting Any file host or CDN A server, container or serverless platform
Speed Very fast, cacheable Depends on code and data sources
Request data (cookies, headers, query) Not available at render time Available
Cost Lowest Compute per request

Astro 5 and later have two output values, static (the default) and server:

JavaScript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

Static output with output: 'static' can still contain dynamic pages: it needs an adapter only once some page opts out of prerendering.

The prerender switch

You decide per page (or endpoint):

ASTRO
---
// src/pages/dashboard.astro, in an output: 'server' project:
// this page runs on every request (default in server mode)
const user = Astro.locals.user;
---
<h1>Hello {user?.name}</h1>
ASTRO
---
// src/pages/about.astro, prerender it even in server mode
export const prerender = true;
---
<h1>About us</h1>
ASTRO
---
// in a static project, opt one page OUT of prerendering
export const prerender = false;
const q = Astro.url.searchParams.get('q');
---
<p>Results for {q}</p>

The rule of thumb: default to static, make dynamic only what needs requests. With output: 'static' plus a few prerender = false pages you get a mostly-static site with a handful of dynamic routes (the older name for this was hybrid mode).

What is available at request time

On non-prerendered pages Astro gives you request data:

ASTRO
---
const method = Astro.request.method;
const lang = Astro.request.headers.get('accept-language');
const theme = Astro.cookies.get('theme')?.value ?? 'light';
const page = Number(Astro.url.searchParams.get('page') ?? 1);
const ip = Astro.clientAddress;

if (!Astro.locals.user) {
  return Astro.redirect('/login');
}
---

Astro.redirect() and returning a Response stop rendering early. You can set status codes with Astro.response.status = 404 and add headers with Astro.response.headers.set(...). Using these on a prerendered page is a build-time warning, because there is no request.

Adapters

An adapter packages your server build for a runtime. Install one with astro add:

Adapter Target
@astrojs/node A Node server (Docker, VPS, Fly, Railway). Modes standalone and middleware
@astrojs/vercel Vercel serverless/edge
@astrojs/netlify Netlify functions
@astrojs/cloudflare Cloudflare Workers/Pages

For Node, astro build produces dist/server/entry.mjs. In standalone mode that file starts an HTTP server itself:

Terminal
npm run build
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs

In middleware mode it exports a handler to mount inside Express or Fastify:

JavaScript
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();
app.use(express.static('dist/client/'));
app.use(ssrHandler);
app.listen(8080);

Pick the adapter that matches where you will host; changing it later is mostly a config change, but some APIs (Node file access, Cloudflare bindings) are platform-specific.

Server islands

A page can stay fully cached while one component is rendered per request. Mark it with server:defer:

ASTRO
---
import Avatar from '../components/Avatar.astro';
---
<header>
  <h1>My shop</h1>
  <Avatar server:defer>
    <span slot="fallback">Loading...</span>
  </Avatar>
</header>

The page HTML (and its CDN cache) is generic. The browser then fetches the Avatar fragment from the server, with the user's cookies, and swaps it in. The fallback appears first. Use it for personalised bits such as the login state, cart count, or recommendations, so the rest of the page keeps CDN speed.

Environment variables

  • import.meta.env.PUBLIC_API_URL is available in client and server code (anything prefixed PUBLIC_ is exposed to the browser).
  • Everything else is server-only: import.meta.env.DATABASE_URL.
  • The type-safe astro:env module lets you declare variables in config with envField (context: 'server', access: 'secret') and import them with validation:
JavaScript
env: {
  schema: {
    API_SECRET: envField.string({ context: 'server', access: 'secret' }),
    PUBLIC_SITE_NAME: envField.string({ context: 'client', access: 'public', default: 'Demo' }),
  },
}

Never put secrets in a PUBLIC_ variable.

Try it: static or dynamic?

A stand-in for the build-time decision. Each route declares whether it uses request data, and the "build" pre-renders the ones that do not.

JS Prerender decision

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: a request-time page

This stand-in renders a "page" from a Request, to show what becomes possible only with SSR: reading cookies and query strings.

JS Render from a Request

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement about default Astro output is correct?

    The default is static output: HTML is generated once at build time and no adapter is needed until a page opts out of prerendering.
  2. 2. In an output: 'static' project, how do you make /search run per request?

    Opt a page out of prerendering with prerender = false and install an adapter to run it.
  3. 3. What does server:defer do?

    A server island is fetched separately from the server, so personalised parts need not make the whole page dynamic.
  4. 4. Which environment variable name is exposed to browser code?

    Only variables prefixed PUBLIC_ are bundled into client code. Everything else is server-only.

Summary

  • Static output is the default; output: 'server' or prerender = false opts into request-time rendering.
  • Decide per page: static unless it needs cookies, headers, queries or live data.
  • An adapter (Node, Vercel, Netlify, Cloudflare) packages the server build for your host.
  • server:defer keeps pages cacheable while personalised pieces stay dynamic.
  • Keep secrets out of PUBLIC_ variables.

Next: API Endpoints