patternjavascriptastroModerate

Astro hybrid rendering: mix static and server-rendered pages

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

Astro 2.6+ (hybrid output mode)

hybrid renderingoutput hybridprerenderSSRstatic generationgetStaticPaths

Error Messages

getStaticPaths() ignored: dynamic routes require server output

Cannot prerender route with dynamic params

Problem

Using output: 'server' makes every page server-rendered, losing static generation benefits for content pages. Using output: 'static' prevents any server-side dynamic behavior.

Solution

Use output: 'hybrid' (Astro 2.6+) or output: 'static' with opt-in SSR:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@sveltejs/adapter-node';

export default defineConfig({
output: 'hybrid', // static by default, SSR opt-in
adapter: node(),
});

// src/pages/blog/[slug].astro — static (default)
---
export async function getStaticPaths() {
const posts = await getCollection('blog');
return posts.map(post => ({ params: { slug: post.slug }, props: { post } }));
}
---

// src/pages/dashboard.astro — server rendered
---
export const prerender = false; // opt-in to SSR
const { user } = Astro.locals;
if (!user) return Astro.redirect('/login');
---

// src/pages/api/subscribe.ts — always server
export const prerender = false;
export const POST: APIRoute = async ({ request }) => { / ... / };

Why

Hybrid rendering lets you prerender marketing pages, blog posts, and docs at build time (fast, cacheable) while keeping dashboards, user-specific pages, and API routes server-rendered. This combines CDN speed with dynamic capability.

Gotchas

In hybrid mode, pages are static by default — add prerender = false to opt into SSR
In server mode, pages are SSR by default — add prerender = true to opt into static
getStaticPaths() is only used in static/hybrid mode for dynamic routes
Server-rendered pages bypass CDN caches — add Cache-Control headers where appropriate

Code Snippets

Hybrid vs server output mode

// astro.config.mjs
export default defineConfig({
  output: 'hybrid',  // pages static by default
  // or: output: 'server'  — pages SSR by default
});

Context

When mixing static and server-rendered pages in an Astro application

Revisions (0)

No revisions yet.