Astro Hybrid Rendering: Old Mode vs What to Use Now

Astro’s hybrid rendering mode, introduced in Astro 3.0, lets you mix static and server-rendered pages in one project. The “old mode” you may have heard about refers to the earlier default behavior where every page was static unless you explicitly opted into server rendering with an adapter. What you should use now depends on your project: for most new sites, the default static mode is still the right choice, but if you need dynamic, per-request data, you should switch to the current hybrid output mode (server output with the hybrid option) or opt into server rendering per page.

Background: How Astro Rendering Evolved

Astro launched in 2021 as a static site generator. Every page was pre-rendered at build time, producing pure HTML, CSS, and JavaScript. This is the “old mode” that many tutorials and early projects used. It was simple and fast, but it couldn’t handle content that changes frequently, like user-specific dashboards or live inventory.

In Astro 3.0 (August 2023), the team introduced an output configuration option. You could set output: 'server' to make every page server-rendered, or output: 'static' to keep the old behavior. Then in Astro 4.0 (December 2023), they added output: 'hybrid', which allows you to mix static and server-rendered pages in the same project. This is the “new mode” that most current documentation recommends for dynamic projects.

The key difference is that in the old static mode, you had no server at runtime. Everything was generated once at build time. In the new hybrid mode, you have a server that can render pages on demand, but you can still pre-render most of your site for speed and SEO.

How the Old Static Mode Worked

In the old mode (Astro 1.x and 2.x), the build process ran a script that fetched all your content, ran your components, and output static files. There was no server process. This meant:

• Every page was generated at build time, so it was identical for every visitor.
• You could use client-side JavaScript to fetch data after page load, but the initial HTML was fixed.
• Deploying was trivial: upload the dist folder to any static host (Netlify, Vercel, GitHub Pages, etc.).
• There was no way to read cookies, headers, or query parameters on the server, so personalization had to happen in the browser.

This mode was perfect for blogs, documentation sites, marketing pages, and portfolios. It’s still the default and recommended for most content-driven sites because it’s fast and cheap to host.

What the New Hybrid Mode Adds

With output: 'hybrid', Astro pre-renders every page by default, just like the old mode. But you can opt individual pages into server rendering by adding export const prerender = false to the page’s frontmatter. Those pages run on a server at request time, so they can:

• Read request headers, cookies, and query parameters.
• Fetch data from a database or API on every request.
• Return different HTML for different users (e.g., a logged-in dashboard).
• Handle form submissions (POST requests) directly.

You need to add an adapter (like @astrojs/node, @astrojs/vercel, or @astrojs/netlify) to your project. The adapter turns your Astro app into a server application that can run on a Node.js server, a serverless function, or an edge function.

In contrast, output: 'server' makes every page server-rendered. That’s useful if you have a web app where nothing is static, but it’s overkill for most sites.

How to Choose What to Use Now

For a new project, start with the default static output. It’s simpler and faster. Only switch to hybrid when you have a specific page that needs server-side data. Here’s a practical decision process:

1. If your site is entirely static (blog, docs, landing pages), use output: 'static' (the default).
2. If you have a few pages that need user-specific data (e.g., account page, search results, cart), use output: 'hybrid' and mark those pages with prerender = false.
3. If you’re building a full web app where most routes are dynamic (like a SaaS dashboard), use output: 'server'.

You don’t need to rewrite existing static sites. The old mode still works in Astro 4 and 5; it’s just called output: 'static' now. The term “old mode” is informal, not an official deprecation.

Common Problems and Misconceptions

One common mistake is thinking that hybrid mode makes all pages server-rendered. It doesn’t—only the ones you explicitly mark. If you forget to add prerender = false, your dynamic page will be static, and your server-side code (like Astro.request.headers) won’t work as expected. You’ll get a build error if you try to use server-only features in a static page, which is helpful.

Another issue is that some static hosts don’t support server rendering. If you deploy a hybrid site to a pure static host (like GitHub Pages), the server-rendered pages will fail. You need a host that runs Node.js or serverless functions. Many popular hosts (Vercel, Netlify, Cloudflare Pages) support this, but you must configure the adapter correctly.

People also confuse hybrid mode with Astro Islands (partial hydration). Islands are about client-side interactivity, not server rendering. You can have islands in static mode—it’s just JavaScript that loads in the browser. Hybrid mode is about where the HTML is generated: at build time or at request time.

Performance and Cost Considerations

Static pages are always faster because they’re served from a CDN edge with no server computation. Server-rendered pages have a small latency overhead (often 50-200ms) and consume compute resources. On serverless platforms, you pay per request, so a high-traffic dynamic page can cost more than a static one.

However, hybrid mode lets you cache server-rendered pages using Astro.response.headers.set('Cache-Control', 'public, max-age=60') or a CDN. You can also use ISR (Incremental Static Regeneration) with adapters like Vercel to revalidate static pages periodically. This gives you the best of both: static speed with fresh data.

For most sites, the performance difference is negligible for a few dynamic pages. The bigger cost is complexity—you now have to manage a server environment, environment variables, and possibly a database connection.

Alternatives and When to Avoid Hybrid

If you need dynamic data but don’t want to manage a server, you can keep your site static and fetch data client-side with fetch() in a script tag or an Island component. This works well for public data (like a weather widget) but not for private user data (like an account page) because the data would be exposed in the browser.

Another alternative is to use a separate backend (like an API route in a different framework) and have Astro call it. This keeps Astro purely static, but you now have two deployments to manage.

Avoid hybrid mode if:

• You’re hosting on a static-only platform.
• You don’t have any dynamic pages.
• You’re new to Astro and want to learn the basics first.
• Your dynamic needs are simple enough for client-side fetching.

If you do need server rendering, hybrid is usually better than full server mode because it lets you keep most of your site static. Only use output: 'server' when the majority of your pages are dynamic.

Frequently Asked Questions

Is the old static mode deprecated?

No. The static output is still fully supported and is the default. The term “old mode” just refers to how Astro worked before server rendering was added. You can continue using it for new projects without any issues.

How do I enable hybrid mode in my Astro project?

Add output: 'hybrid' to your astro.config.mjs file, and install an adapter like @astrojs/node or @astrojs/vercel. Then, on any page that should be server-rendered, add export const prerender = false to the frontmatter.

Can I mix static and server pages in the same project?

Yes, that’s exactly what hybrid mode does. Pages without the prerender = false flag are static; pages with it are server-rendered. You can have both in the same project.

What happens if I use server-only features in a static page?

Astro will throw a build error. For example, accessing Astro.request.headers in a page that is prerendered will fail at build time, telling you to set prerender = false.

Do I need a Node.js server to run hybrid mode?

You need a runtime that supports the adapter you choose. For local development, Astro starts a dev server. For production, you need a server or serverless platform that runs the adapter (Node.js, Deno, or edge functions).

Can I use hybrid mode with a static host like GitHub Pages?

No. GitHub Pages only serves static files. You’d need to use a host that supports server-side rendering, like Vercel, Netlify, or Cloudflare Pages. Alternatively, keep your site static and use client-side fetching for dynamic data.

Related

• AI Evaluation Benchmarks: Which to Use
• AI Adoption Speed & Agentic AI Talent Needs
• IPS Monitors and Eye Comfort: What Panels Can and Can’t Do