# Astro Static, Hybrid, and Server Output Modes: A Complete Configuration Guide

> Explore Astro's static and server output modes. Understand their differences in build artifacts, adapter needs, and hosting architecture for optimal site performance. Configure Astro effectively.

- Repository: [Astro/astro](https://github.com/withastro/astro)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Astro offers two distinct output modes—`static` (which absorbed the former hybrid behavior) that prerenders pages by default with optional server-side rendering via `export const prerender = false`, and `server` which forces SSR for every request—determining build artifacts, adapter requirements, and hosting architecture.**

The `withastro/astro` framework provides flexible rendering strategies through its output configuration, allowing developers to optimize for static site generation or full server-side rendering. Understanding the differences between Astro's static and server-only output modes is essential for architecting performant applications, as this choice affects everything from build artifacts in `packages/astro/src/core/` to adapter integration and runtime behavior.

## Understanding Astro's Output Configuration

Astro defines its output behavior through the `output` field in `astro.config.mjs`. According to the type definitions in [`packages/astro/src/types/public/config.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/types/public/config.ts) (lines 15-20), only two valid values exist: `'static'` and `'server'`. The former `output: 'hybrid'` option was removed in Astro 5, with its functionality merged into the static mode.

## Static Output Mode (Formerly Hybrid)

In `output: 'static'` mode, Astro **prerenders every page at build time** by default, generating plain HTML files that can be served from a CDN. This behavior, previously called "hybrid" mode, allows specific pages to opt out of prerendering using the `export const prerender = false` directive.

As documented in [`packages/astro/src/core/README.md`](https://github.com/withastro/astro/blob/main/packages/astro/src/core/README.md) (line 46), the build pipeline treats static output as a hybrid generation process, creating HTML files for prerendered routes while reserving server runtime capabilities for opted-out routes.

### Configuration Example

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  // All pages prerendered by default (Astro 5+)
  output: 'static',
});

```

### Opting Out of Prerendering

To force server-side rendering for specific routes in static mode, export the `prerender` constant:

```astro
---
// src/pages/dashboard.astro
export const prerender = false;
---
<h1>Dashboard (SSR)</h1>
<p>Personalized data for {Astro.request.user?.name}</p>

```

## Server Output Mode

Setting `output: 'server'` forces **every page to render on the server at request time**. No HTML files are emitted during the build process; instead, Astro relies entirely on server-side rendering (SSR) for all routes. This mode requires an adapter capable of handling a full server runtime.

### Configuration Example

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

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

```

```astro
---
// src/pages/index.astro
import { fetchProducts } from '../lib/api';
const products = await fetchProducts(); // Executes on every request
---
<h1>Product Catalogue (SSR)</h1>
<ul>
  {products.map(p => <li>{p.name}</li>)}
</ul>

```

## Key Differences: Static vs Server Output

Understanding the architectural implications of each mode helps determine the optimal configuration for your project.

**Rendering Timing**
- **Static mode**: Pages build as HTML files at build time, with optional SSR for specific routes using `prerender = false`.
- **Server mode**: Every request triggers server-side rendering; no static HTML files exist.

**Adapter Requirements**
- **Static mode**: Adapters treat the build as a static site, copying generated HTML files to the deployment output. They require only minimal runtime capabilities for non-prerendered pages.
- **Server mode**: Adapters expect a full server runtime because every request may hit a server-rendered route, requiring continuous backend availability.

**Performance and Cost**
- **Static mode**: Most traffic serves from a CDN (static files), minimizing latency and cost. Server-rendered routes incur compute costs only for pages that explicitly require dynamic data.
- **Server mode**: Every request hits a server, increasing latency and requiring payment for continuously running backend infrastructure.

**Ideal Use Cases**
- **Static mode**: Content-heavy sites requiring the speed of static files but needing a handful of dynamic endpoints (authentication, API routes, personalized pages).
- **Server mode**: Fully dynamic applications such as dashboards, e-commerce carts, or real-time data displays where every page depends on request-time data.

## Migrating from Hybrid to Static (Astro 5+)

The `output: 'hybrid'` option was removed in Astro 5, with its behavior merged into `output: 'static'`. As noted in [`packages/astro/CHANGELOG.md`](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) (around line 5295), the new static mode provides the exact same functionality—prerendering by default with opt-out support—without requiring experimental flags.

**Before (Astro <5):**

```javascript
// astro.config.mjs
export default defineConfig({
  output: 'hybrid',
  experimental: { hybridOutput: true },
});

```

**After (Astro 5+):**

```javascript
// astro.config.mjs
export default defineConfig({
  output: 'static', // Same behaviour as old 'hybrid'
});

```

## Summary

- Astro provides two output modes defined in [`packages/astro/src/types/public/config.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/types/public/config.ts): `'static'` and `'server'`.
- **Static mode** (formerly hybrid) prerenders all pages at build time by default, allowing specific routes to opt into SSR via `export const prerender = false`.
- **Server mode** forces SSR for every request, emitting no static HTML files and requiring a full server runtime adapter.
- The `output: 'hybrid'` option was removed in Astro 5; use `output: 'static'` to achieve the same behavior.
- Choose static mode for content-heavy sites with occasional dynamic needs, and server mode for fully dynamic applications.

## Frequently Asked Questions

### What happened to Astro's hybrid output mode?

Astro removed the `output: 'hybrid'` configuration option in version 5, merging its functionality into `output: 'static'`. As documented in [`packages/astro/CHANGELOG.md`](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md), the new static mode behaves exactly like the old hybrid mode—prerendering pages by default while supporting server-side rendering for routes that export `prerender = false`.

### Can I mix static and server-rendered pages in the same Astro project?

Yes, but only when using `output: 'static'`. In static mode, all pages are prerendered at build time by default, but you can opt individual pages out of prerendering by adding `export const prerender = false` to the frontmatter. This creates a hybrid architecture where most content serves from a CDN while specific routes (like authentication pages or dashboards) render on the server.

### Which output mode should I choose for a content-heavy blog with a few dynamic features?

Use `output: 'static'` (the default). This mode generates static HTML files for all your blog posts at build time, allowing them to be cached on a CDN for maximum performance. For the few dynamic features—such as a personalized user dashboard or authentication callbacks—simply add `export const prerender = false` to those specific page files to enable server-side rendering only where needed.

### What are the performance implications of using server-only output mode?

Server mode (`output: 'server'`) increases latency and hosting costs because every page request triggers server-side rendering with no static HTML files to serve from the edge. As implemented in `packages/astro/src/core/`, this mode requires a continuously running backend and an adapter capable of handling full SSR workloads, making it ideal for highly dynamic applications but less efficient for content that rarely changes.