Skip to main content
Astro offers flexible rendering modes that let you choose how each page in your project is built and delivered. You can use static site generation (SSG), server-side rendering (SSR), or combine both in a hybrid approach.

​
Output Modes

Astro supports three output modes, configured in your astro.config.mjs file: 
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static'
});

​
Static Mode

Default behavior. All pages are pre-rendered at build time into static HTML files.
Static mode is ideal for content-heavy sites where pages don’t change frequently, providing the best performance and lowest hosting costs.
src/pages/index.astro
---
// This page is pre-rendered at build time
const data = await fetch('https://api.example.com/data').then(r => r.json());
---

<html>
  <body>
    <h1>Static Page</h1>
    <p>Built at: {new Date().toISOString()}</p>
  </body>
</html>

​
Server Mode

All pages rendered on-demand. Pages are rendered on the server for each request, allowing for dynamic content and server-side logic.
Server mode requires an adapter to deploy to your hosting platform.
src/pages/api/user.astro
---
// This page is rendered on every request
const { cookies } = Astro;
const userId = cookies.get('userId');

const user = await db.users.find(userId);
---

<html>
  <body>
    <h1>Welcome, {user.name}</h1>
    <p>Rendered at: {new Date().toISOString()}</p>
  </body>
</html>

​
Hybrid Mode

Mix static and server rendering. Pages are pre-rendered by default, but you can opt-in to on-demand rendering for specific pages.
src/pages/product/[id].astro
---
export const prerender = false; // Opt-in to server rendering

const { id } = Astro.params;
const product = await db.products.find(id);
---

<html>
  <body>
    <h1>{product.name}</h1>
    <p>Real-time stock: {product.stock}</p>
  </body>
</html>

​
Page-Level Control

You can control rendering per-page using the prerender export:
In output: 'server' mode, pages are server-rendered by default. Use export const prerender = true to pre-render specific pages:
src/pages/about.astro
---
export const prerender = true; // Pre-render this page
---

<html>
  <body>
    <h1>About Us</h1>
  </body>
</html>

​
Adapters

To use SSR, you need an adapter for your deployment platform. Adapters allow Astro’s server output to work with your hosting provider’s runtime.

​
Official Adapters

Node.js

Deploy to any Node.js server

Vercel

Deploy to Vercel’s edge network

Netlify

Deploy to Netlify functions

Cloudflare

Deploy to Cloudflare Workers

​
Installing an Adapter

1

Add the adapter

npx astro add node
2

Configure output mode

The adapter will automatically configure your astro.config.mjs:
astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

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

Build and deploy

npm run build
Your server-rendered site is ready to deploy!

​
Build Process

During the build process, Astro analyzes your routes and determines how each should be rendered based on your configuration:
  • All pages are rendered to HTML at build time
  • Assets are optimized and bundled
  • Output is a directory of static files ready to serve
  • Located in dist/ by default
  • Creates a server entry point for on-demand rendering
  • Pre-renders pages marked with prerender: true
  • Bundles server-side code and dependencies
  • Outputs both static assets and server chunks

​
When to Use Each Mode

Static

Best for:
  • Blogs and documentation
  • Marketing sites
  • Content-heavy sites
  • Maximum performance

Server

Best for:
  • User dashboards
  • Personalized content
  • Real-time data
  • Authentication required

Hybrid

Best for:
  • E-commerce sites
  • SaaS applications
  • Mixed content types
  • Optimal flexibility

​
Performance Considerations

For optimal performance, pre-render as much as possible and use server rendering only where dynamic data is truly necessary.

​
Static Generation Benefits

  • Fastest possible load times - No server computation required
  • Easy to cache - CDN-friendly static files
  • Lower hosting costs - Simple file hosting
  • Better SEO - Instant content availability

​
Server Rendering Benefits

  • Fresh data - Always up-to-date content
  • Personalization - User-specific pages
  • Security - Hide sensitive logic
  • Dynamic behavior - Respond to request data

Adapters

Learn about deployment adapters

Server Islands

Mix static and dynamic content

Middleware

Add server-side logic

Actions

Handle form submissions

Build docs developers (and LLMs) love

Get started for freeTalk to us