AstroHow-ToBeginner · 4 min read

How to Use Output Hybrid in Astro: Syntax and Example

In Astro, use output: 'hybrid' in your astro.config.mjs to enable both static site generation and server-side rendering. This lets you serve static pages while also supporting dynamic server-rendered pages in the same project.

📐

Syntax

To enable hybrid output in Astro, set the output property to 'hybrid' at the root level in astro.config.mjs. This tells Astro to build static pages by default but also prepare server-side rendering for dynamic routes.

Key parts:

output: 'hybrid' - enables hybrid rendering mode.
adapter-node or other server adapter - required to run server-rendered pages.

javascript

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'hybrid',
  adapter: node(),
});

💻

Example

This example shows a simple Astro project configured for hybrid output. Static pages like /index.astro are pre-rendered, while dynamic pages like /api/data.astro can use server-side logic.

astro

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

export default defineConfig({
  output: 'hybrid',
  adapter: node(),
});

// src/pages/index.astro
---
const title = 'Welcome to Hybrid Output';
---
<html lang="en">
  <head><title>{title}</title></head>
  <body>
    <h1>{title}</h1>
    <p>This page is statically generated.</p>
  </body>
</html>

// src/pages/api/data.astro
---
export async function get() {
  return {
    body: JSON.stringify({ message: 'This is server-rendered data' }),
  };
}
---

Output

<h1>Welcome to Hybrid Output</h1> <p>This page is statically generated.</p>

⚠️

Common Pitfalls

Common mistakes when using output: 'hybrid' include:

Not installing or configuring a server adapter like @astrojs/node, which is required to run server-rendered pages.
Expecting all pages to be server-rendered; by default, pages without server code remain static.
Forgetting to deploy the project to a Node.js environment to support server rendering.

javascript

/* Wrong: Missing adapter causes server pages to fail */
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'hybrid',
  // adapter missing here
});

/* Right: Add node adapter for server support */
import node from '@astrojs/node';

export default defineConfig({
  output: 'hybrid',
  adapter: node(),
});

📊

Quick Reference

output: 'hybrid' - enables static + server rendering.
adapter-node - required for server runtime.
Static pages are pre-built; dynamic pages run on server.
Deploy to Node.js environment for server features.

✅

Key Takeaways

Set output: 'hybrid' in astro.config.mjs to enable hybrid rendering.

Install and configure a server adapter like @astrojs/node to run server-rendered pages.

Static pages remain pre-built; dynamic pages use server-side rendering.

Deploy your Astro project to a Node.js environment to support hybrid output.

Hybrid output lets you combine fast static pages with dynamic server features in one project.