# Deploying Astro websites with hybrid rendering
- Date: 2026-01-16T11:25:33.267Z
- Tags: Platform
- URL: https://render.com/articles/deploying-astro-websites-with-hybrid-rendering
Imagine deploying a web application where marketing pages load instantly from a global CDN while your user dashboard fetches fresh data on every request, all from a single codebase. That's the power of hybrid rendering in Astro. Instead of choosing one rendering strategy for your entire site, Astro lets you mix and match: some pages generate statically at build time for blazing-fast performance, while others render server-side per request to serve dynamic, personalized content. In this article, you'll learn how Astro's rendering modes work, and see practical configuration examples for hybrid deployments.
## Understanding Astro's rendering modes
Astro implements two primary rendering strategies: static site generation (SSG) and server-side rendering (SSR). Static site generation produces HTML files during the build process, delivering pre-rendered content through CDN distribution. Server-side rendering executes page logic per request, enabling dynamic data fetching and user-specific content.
Astro's hybrid architecture enables per-route rendering decisions through explicit opt-in mechanisms. You configure a base rendering mode, then selectively override this default on specific pages using export declarations.
Consider these key criteria when choosing your rendering strategy:
- *Content update frequency*: Static content changing daily or less favors SSG, while frequent updates favor SSR
- *Personalization requirements*: User-specific content requires SSR
- *Data source characteristics*: Build-time accessible data suits SSG, while authenticated API calls require SSR
- *Traffic patterns*: High-traffic pages with identical content benefit from static caching
Optimal hybrid implementations use SSR strategically for specific dynamic requirements while maintaining static generation for consistent content. Marketing pages, documentation, and blog posts perform optimally as static assets. User dashboards, real-time data displays, and authenticated content justify SSR overhead. For more information on Render's static site hosting, see [Render Static Sites documentation](https://render.com/docs/static-sites).
## Configuring hybrid rendering
Astro's configuration system determines rendering behavior through the `astro.config.mjs` file. The `output` property establishes the base rendering mode: `'static'` for pure SSG, `'server'` for universal SSR, or `'hybrid'` enabling mixed strategies.
Static output produces HTML files suitable for CDN distribution. Server and hybrid modes generate server application artifacts requiring Node.js runtime environments. On Render, static output deploys to [Static Sites](https://render.com/docs/static-sites), while server and hybrid configurations require [Web Services](https://render.com/docs/web-services).
This simplified configuration demonstrates the hybrid mode setup:
```javascript
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
output: 'hybrid',
adapter: node({
mode: 'standalone'
}),
integrations: []
});
```
The adapter property specifies your deployment target's server environment. `@astrojs/node` provides Node.js runtime compatibility required by Render Web Services. Install the adapter with: `npm install @astrojs/node`.
To control individual page rendering, you'll use the `prerender` export:
```javascript
---
export const prerender = false; // Triggers SSR for this page
const response = await fetch('https://api.example.com/data');
const data = await response.json();
---
Dynamic Page
Server-Rendered Content
Fetched at: {new Date().toISOString()}
{JSON.stringify(data, null, 2)}
```
The `prerender` export controls individual page rendering. In hybrid mode, `prerender: false` designates SSR execution. In server mode, `prerender: true` forces static generation.
## Content collections and static optimization
Content collections represent structured content directories managed through schema definitions. Collections typically remain statically generated because content files change through deployment cycles rather than per-request.
This pattern illustrates content collection usage:
```javascript
---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
const published = posts
.filter(post => !post.data.draft)
.sort((a, b) => b.data.date - a.data.date);
---
```
Dynamic collection rendering becomes appropriate when content sources exist outside the build process—headless CMS platforms, external databases, or frequently updated APIs.
## Deploying to Render
To deploy your hybrid Astro application, configure a Web Service on Render. Web Services provide Node.js runtime environments necessary for server-side rendering execution.
*Build command:* `npm run build` executes Astro's build process, applying configuration and generating output in the `dist/` directory.
*Start command:* `node ./dist/server/entry.mjs` initiates the server process, handling incoming HTTP requests and routing them to appropriate static files or SSR handlers. For detailed configuration options, see [Render's Web Services documentation](https://render.com/docs/web-services).
Environment variables enable different behavior across environments. `NODE_ENV=production` activates production optimizations. You can pass API keys and credentials through Render's environment variable interface.
Resource allocation depends on traffic patterns and SSR complexity. Static pages serve with minimal resource consumption. SSR routes executing complex data fetching require appropriate memory and CPU allocation. Render's [pricing structure](https://render.com/pricing) offers various instance types matching different performance requirements.
## Before you begin, ensure you have the following:
- Astro version 2.0 or higher for stable hybrid rendering support
- Node.js runtime version 18.x or higher
- Required packages: `astro` and `@astrojs/node`
- Git repository hosting on GitHub, GitLab, or Bitbucket
- Committed lock files for reproducible builds
## Troubleshooting common deployment issues
*Build failures:* Verify all required packages appear in dependencies and commit lock files. Install adapter with `npm install @astrojs/node`.
*Server start failures:* Verify start command `node ./dist/server/entry.mjs` matches adapter output. Check that you've configured all required environment variables.
*404 errors on SSR routes:* Confirm `prerender: false` exports exist on dynamic routes. Verify `output: 'hybrid'` in your configuration file.
*Memory exhaustion:* Increase instance memory allocation through Render service settings. Profile SSR routes for inefficient data fetching patterns.
*Static asset loading issues:* Configure `site` and `base` properties in your Astro configuration. Use `Astro.url` for dynamic path construction.
*Build timeout errors:* Optimize build performance by reducing dependency installation time and minimizing expensive computation in build scripts.
## FAQs
###### What is hybrid rendering in Astro?
Hybrid rendering lets you mix static site generation (SSG) and server-side rendering (SSR) in a single Astro project. Some pages generate at build time for fast CDN delivery, while others render per request for dynamic, personalized content.
###### When should I use SSG vs. SSR?
Use SSG for content that changes infrequently, like marketing pages, documentation, and blog posts. Use SSR for user-specific content, real-time data, or pages requiring authenticated API calls.
###### How do I enable hybrid mode in Astro?
Set `output: 'hybrid'` in your `astro.config.mjs` file and install a server adapter like `@astrojs/node`. Then use the `prerender` export on individual pages to control their rendering behavior.
###### What does the prerender export do?
The `prerender` export controls how a specific page renders. In hybrid mode, set `export const prerender = false` to enable SSR for that page. In server mode, set it to `true` to force static generation.
###### Why do I need the @astrojs/node adapter?
The Node.js adapter enables your Astro app to run on Node.js server environments like Render Web Services. It generates the server entry point required to handle SSR requests.
###### Should I deploy to a Static Site or Web Service on Render?
If your Astro project uses `output: 'static'`, deploy to a Static Site. If you use `output: 'hybrid'` or `output: 'server'`, deploy to a Web Service because you need a Node.js runtime for SSR.
###### What start command should I use on Render?
Use `node ./dist/server/entry.mjs` as your start command. This launches the server generated by the Node.js adapter after running `npm run build`.
###### Why am I getting 404 errors on my SSR routes?
Verify that your dynamic pages include `export const prerender = false` in the frontmatter. Also confirm that your `astro.config.mjs` has `output: 'hybrid'` or `output: 'server'` configured.
###### Can I use content collections with hybrid rendering?
Yes. Content collections typically remain statically generated because they change during deployments, not per request. However, you can render them dynamically if your content comes from external sources like a headless CMS.
###### What Node.js version does Astro require?
Astro requires Node.js version 18.x or higher for stable hybrid rendering support.