Astro SSR Modes — Static, Server, and Hybrid Rendering

In this tutorial, you will learn about Astro SSR Modes. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Astro SSR modes: static generation, server-side rendering, hybrid mode, and how to choose the right rendering strategy for each page.

In this lesson, you'll configure SSR adapters, switch between static and server rendering, use hybrid mode for per-route strategies, and deploy server-rendered Astro apps.

What You'll Learn

How to enable SSR with adapters, configure static vs server per route, use output: 'hybrid' for mixed rendering, and deploy SSR apps.

Why It Matters

Not every page needs server rendering. Static pages are faster and cheaper. SSR pages handle dynamic content. Hybrid mode lets you choose per route for optimal performance and cost.

Real-World Use

DodaTech uses hybrid mode: tutorial pages are static (pre-built HTML), user dashboards are server-rendered (personalized content), and the search page uses SSR for real-time queries.

flowchart TD
    A[Astro Config] --> B{output mode}
    B -->|static| C[Static HTML]
    B -->|server| D[Request-time Render]
    B -->|hybrid| E[Per-Route Strategy]
    C --> F[CDN Deploy]
    D --> G[Node/Edge Server]
    style A fill:#ff5a03,color:#fff

Static Mode (Default)

Astro generates all pages at build time:

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  output: "static",
});

Every page becomes a pre-built HTML file. Deploy to any static host (Netlify, Cloudflare Pages, S3).

Server Mode

Enable SSR with an Adapter:

npx astro add netlify

Configure:

// astro.config.mjs
import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify";

export default defineConfig({
  output: "server",
  adapter: netlify(),
});

Pages render on each request. Use for personalized content, authenticated pages, or real-time data.

Hybrid Mode

Choose per-route rendering:

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

export default defineConfig({
  output: "hybrid",
  adapter: node({ mode: "standalone" }),
});

Mark individual pages for prerendering:

---
// src/pages/about.astro
export const prerender = true;
---
<h1>About (static)</h1>

Or keep them as server-rendered (default in hybrid mode):

---
// src/pages/dashboard.astro
// No prerender export — renders on each request
const user = await getUser(Astro.request);
---
<h1>Welcome, {user.name}</h1>

SSR with API Endpoints

SSR mode enables API routes:

---
// src/pages/api/users.astro
export async function get(Astro) {
  const users = await db.query("SELECT * FROM users");
  return new Response(JSON.stringify(users), {
    headers: { "Content-Type": "application/json" },
  });
}
---

The API endpoint responds to GET requests with JSON data.

Performance Comparison

Common Mistakes

1. Forgetting the adapter in server mode: SSR requires an adapter. Without it, npm run build fails with a missing adapter error.
2. Using browser APIs in SSR pages: window, document, and localStorage don't exist on the server. Guard with typeof window !== 'undefined'.
3. Setting prerender: true on dynamic data pages: Pages with per-request data (user-specific content) should not be prerendered.
4. Not handling server errors: SSR pages need error boundaries. Use Astro.response.status = 500 for error cases.
5. Mixing static and server assets: Static pages are served from CDN. Server pages run on a runtime. Ensure your hosting supports both.

Practice Questions

1. What is the default output mode in Astro? Answer: static. All pages are pre-built as HTML files during the build step.

2. How do you enable server-side rendering? Answer: Set output: "server" in config and add an adapter like @astrojs/netlify or @astrojs/node.

3. What is hybrid mode? Answer: A mix of static and server rendering where individual pages opt into prerendering with export const prerender = true.

4. Why would you use hybrid mode? Answer: To pre-build static marketing pages while keeping personalized dashboards or authenticated pages server-rendered.

Challenge

Set up a project in hybrid mode: make your homepage and about page static, your dashboard and profile pages server-rendered, and verify the build output shows a mix of HTML files and server handlers.

Mini Project

Build a site with three rendering strategies: a static blog, a server-rendered user profile page that fetches from an API, and a hybrid search results page that pre-renders popular queries.

FAQ

What's Next

Learn how to create Astro API Endpoints for handling form submissions and serving JSON data.