Choosing Astro's Output Mode: Static, Server, or Hybrid

Decision: Match output mode to request-time data needs

If an Astro page needs cookies, headers, query parameters, or database results that exist only when a visitor requests the page, static output will not work. You must use server or hybrid mode. This guide helps you choose between static, server, and hybrid based on content freshness, infrastructure constraints, and request-time data requirements.

Constraints and supported options

The output setting in astro.config.mjs controls when HTML is produced. 'Prerendered' means generated at build time. An 'adapter' is a package that connects Astro to a Node.js hosting environment. The three supported values are static, server, and hybrid. Server and hybrid modes require a Node.js-compatible adapter such as @astrojs/node; without one, the build fails. This assumes a current Astro project with Node.js installed.

Output mode	When HTML is generated	Request data access	Required infrastructure	Content update path
static (default)	Build time, all pages	No	CDN or file server only	Rebuild and redeploy
server	Per request, all pages	Yes	Node.js server with adapter	Immediate on next request
hybrid	Build time by default; per request where opted out	Yes, only on opted-out routes	Node.js server with adapter	Rebuild for static routes; immediate for server routes

When to choose each mode

Choose static for marketing sites, documentation, and blogs where content changes infrequently and no user-specific data is needed at render time. Choose server for authenticated dashboards or applications where nearly every page depends on request context. Choose hybrid when most pages are public and cacheable, but a few routes—such as a user profile or API endpoint—must render on demand.

Trade-offs

Static output is the cheapest to operate because it needs no application server, but every content change requires a new build. Server output removes rebuilds for dynamic content but adds runtime latency, adapter configuration, and hosting costs. Hybrid mode keeps most pages on a CDN while isolating dynamic routes to a Node server, which is useful when only a small subset of pages needs authentication or real-time data.

Implementation: hybrid with a server-rendered route

This example configures a mostly static site that renders one route on demand.

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

export default defineConfig({
  output: 'hybrid',
  adapter: node(),
});

Install the adapter from the project directory:

npm install @astrojs/node

Mark a page as non-prerendered so Astro renders it per request:

// src/pages/api/user.astro
export const prerender = false;

export async function GET({ request }) {
  const url = new URL(request.url);
  const id = url.searchParams.get('id');
  return new Response(`User ${id}`);
}

Run the build from the project root. No special permissions are required.

npx astro build

Expected result: prerendered routes appear as HTML files under dist/, while api/user is handled by the Node adapter at request time. The request object is unavailable on prerendered pages, even in hybrid mode. Risk: omitting the adapter while output is server or hybrid causes a configuration failure.

Validation and constraints

• Run npx astro build. If output is server or hybrid and no adapter is installed, the build fails with a configuration error.
• Confirm Astro.request is used only on routes with export const prerender = false.
• Verify adapter compatibility with your deployment platform before selecting server or hybrid.

Rollback

Changing output alters build artifacts. To revert, set output back to static, remove the adapter import if no routes require server rendering, and run npx astro build again.

Practical check

After building, inspect dist/. Prerendered routes appear as static HTML files. Routes with prerender = false do not produce a standalone HTML file and instead depend on the Node adapter at request time.