Astro SSR and Hybrid Rendering

Control rendering mode at the project level and per-page — combine static pre-rendering with server-side dynamic pages using

output: 'hybrid'

and adapter configuration.

When to Use

• You need some pages to be server-rendered (authenticated dashboards, personalized content, real-time data) while others stay static
• You are adding authentication, user sessions, or cookie-based personalization to an Astro project
• You want to read

  Astro.request

  headers,

  Astro.cookies

  , or

  Astro.locals

  in a page
• You are selecting an adapter for a deployment target (Vercel, Node.js, Cloudflare)
• You need to understand which features (redirects, cookies,

  Astro.params

  ) are available in SSG vs. SSR mode

Instructions

1. Set the

   output

   field and install an adapter in

   astro.config.mjs

   :

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

export default defineConfig({
  output: 'server', // all pages are SSR by default
  adapter: vercel(),
});

Available

output

• 'static'

  (default) — all pages pre-rendered at build time; no server required

• 'server'

  — all pages SSR; a server adapter is required

• 'hybrid'

  — all pages static by default; opt specific pages into SSR with

  prerender = false

2. In

   output: 'hybrid'

   mode, opt a page into SSR by exporting

   prerender = false

   :

---
// src/pages/dashboard.astro
export const prerender = false; // This page is server-rendered

const user = Astro.locals.user;
if (!user) return Astro.redirect('/login');
const data = await fetchUserData(user.id);
---
<h1>Welcome, {user.name}</h1>

3. In

   output: 'server'

   mode, opt a page into static pre-rendering by exporting

   prerender = true

   :

---
// src/pages/about.astro
export const prerender = true; // Pre-render this page at build time
---
<h1>About Us</h1>

4. Use

   Astro.request

   to read request data in SSR pages. This is a standard

   Request

   object:

---
export const prerender = false;

const url = new URL(Astro.request.url);
const query = url.searchParams.get('q') ?? '';
const userAgent = Astro.request.headers.get('user-agent');
const clientIp = Astro.clientAddress; // requires adapter support
---

5. Read and write cookies with

   Astro.cookies

   :

---
export const prerender = false;

// Read a cookie
const theme = Astro.cookies.get('theme')?.value ?? 'light';

// Set a cookie
Astro.cookies.set('theme', 'dark', {
  httpOnly: false,
  secure: true,
  sameSite: 'lax',
  maxAge: 60 * 60 * 24 * 365, // 1 year
  path: '/',
});
---

6. Return a redirect from a page with

   Astro.redirect()

   :

---
export const prerender = false;

const session = Astro.cookies.get('session')?.value;
if (!session) return Astro.redirect('/login', 302);
---

7. Install the correct adapter for your deployment target:

# Vercel
npx astro add vercel

# Node.js (standalone server)
npx astro add node

# Cloudflare Pages/Workers
npx astro add cloudflare

# Netlify
npx astro add netlify

8. For dynamic routes in SSR mode, do not implement

   getStaticPaths()

   . Astro reads

   Astro.params

   directly from the request URL:

---
// src/pages/blog/[slug].astro
export const prerender = false;

const { slug } = Astro.params;
const post = await fetchPost(slug);
if (!post) return Astro.redirect('/404');
---
<article><h1>{post.title}</h1></article>

Details

Astro's rendering model is a spectrum from fully static to fully dynamic. Understanding which mode to use for each page is the key design decision in an Astro SSR project.

When to use each mode:

prerender = true

prerender = false

prerender = true

prerender = false

prerender = false

prerender = true

output: 'hybrid'

output: 'server'

Choose

output: 'hybrid'

output: 'server'

Adapter selection:

The adapter transforms Astro's SSR output into the format required by the target platform:

• @astrojs/vercel/serverless

  — Vercel serverless functions

• @astrojs/vercel/edge

  — Vercel Edge Functions (limited Node.js API surface)

• @astrojs/node

  — standalone Node.js server (requires

  node src/server.mjs

  )

• @astrojs/cloudflare

  — Cloudflare Pages / Workers (no Node.js built-ins)

• @astrojs/netlify

  — Netlify Functions / Edge Functions

Astro.locals

Middleware populates

Astro.locals

Astro.locals

Streaming:

Astro supports streaming SSR responses. The page begins streaming HTML to the client before all async data is resolved. Components that are not awaited render as placeholders until their data arrives. This improves Time To First Byte (TTFB) for pages with multiple independent async data sources.

Environment variables in SSR:

Use

import.meta.env.SECRET_API_KEY

PUBLIC_

Source

https://docs.astro.build/en/guides/server-side-rendering

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.