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.

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, while server and hybrid configurations require Web Services.

This simplified configuration demonstrates the hybrid mode setup:

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:

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:

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.

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 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