How to Use Render with Astro: Complete Guide

Render is a cloud application hosting platform that focuses on simplicity. It provides automatic deploys from Git, managed databases, free SSL, and a straightforward dashboard. For Astro developers, Render offers two relevant options: free static site hosting for pre-rendered Astro sites, and web services starting at $7/month for SSR deployments. If you have tried Heroku and wished it were simpler and cheaper, Render is the modern alternative.

The deployment process is clean. Connect your Git repo, tell Render how to build your project, and it handles the rest. No Docker files, no infrastructure config, no YAML pipelines.

Prerequisites

• Node.js 22.12.0 or newer. Astro 6 dropped support for Node 18 and Node 20 and now requires Node 22 (@astrojs/node 10.x targets Astro 6 as its peer dependency). Render defaults to a recent Node 24 release, so the platform default is already compatible. Pin your version with a .nvmrc or a NODE_VERSION environment variable if you want it explicit.
• An Astro project (npm create astro@latest)
• A Render account (free tier for static sites)
• Your project in a GitHub or GitLab repository

Installation

For a static Astro site, no extra packages are needed. The output option defaults to static in Astro 6, so an empty config already prerenders your whole site:

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  // output defaults to "static" in Astro 6
});

For on-demand (SSR) deployments, add the Node adapter. The recommended way is the astro add command, which installs the package and wires up the config in one step:

npx astro add node

That produces a config like this:

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

export default defineConfig({
  adapter: node({
    mode: "standalone",
  }),
});

Note the Astro 6 change. You no longer set output: "server" just to deploy on a server. With an adapter present, pages still prerender by default, and you opt individual routes into on-demand rendering with export const prerender = false. If you want the inverse (every page server-rendered by default), set output: "server" and opt static pages back in with export const prerender = true. The old output: "hybrid" mode was removed in Astro 5, so do not add it; mixed static and on-demand rendering is now the normal behavior. The Node adapter's mode can be "standalone" (the entry file starts its own HTTP server, which is what you want on Render) or "middleware" (for mounting inside Express or Fastify).

Configuration

For static sites, go to Render's dashboard and create a new "Static Site":

1. Connect your GitHub or GitLab repository
2. Set the build command: npm run build
3. Set the publish directory: dist

That is it. Render detects the Node.js environment, runs your build, and serves the output from its CDN.

One gotcha worth knowing up front. The publish directory is dist for a fully static build, but if any page in your project is rendered on demand (you added an adapter and set prerender = false somewhere), Astro writes the static assets to dist/client instead. Astro's official Render guide calls this out directly, so set the publish directory to dist/client the moment you introduce a single on-demand route.

For SSR sites, create a "Web Service" instead and configure the start command:

# Build command
npm install && npm run build

# Start command
node ./dist/server/entry.mjs

Critical detail for web services. Astro's standalone server binds to localhost by default, which Render's load balancer cannot reach. Render's own Astro guide says to set the HOST environment variable to 0.0.0.0 on the web service so the server listens on all interfaces. The standalone entry also reads PORT, and Render injects one automatically, so you usually do not need to set it yourself.

Add a render.yaml to your project root for infrastructure-as-code:

# render.yaml
services:
  - type: web
    name: my-astro-site
    runtime: node
    buildCommand: npm install && npm run build
    startCommand: node ./dist/server/entry.mjs
    envVars:
      - key: NODE_ENV
        value: production
      - key: HOST
        value: 0.0.0.0

Do not hardcode a PORT value here. Render assigns the port and passes it to your service through the PORT environment variable, and the Astro standalone server reads it automatically. Setting HOST to 0.0.0.0 is the field that actually matters, since it is what lets Render's router reach the process.

For static sites, the render.yaml looks simpler:

# render.yaml
services:
  - type: web
    name: my-astro-site
    runtime: static
    buildCommand: npm install && npm run build
    staticPublishPath: ./dist
    headers:
      - path: /*
        name: X-Frame-Options
        value: DENY

Environment variables are configured through the Render dashboard or the render.yaml file:

# In Render Dashboard > Environment
SITE_URL=https://yourdomain.com
API_KEY=your-api-key

Basic Usage

After connecting your repo, every push to your main branch triggers an automatic deploy. The typical workflow looks like this:

# Make changes locally
git add .
git commit -m "Add new blog post"
git push origin main
# Render automatically builds and deploys

For custom domains, go to your Render service settings and add your domain. Render automatically provisions an SSL certificate via Let's Encrypt.

You can set up a custom 404 page for static sites by adding a redirect rule in the Render dashboard:

Source: /*
Destination: /404.html
Status: 404

For SSR deployments, handle 404s in your Astro middleware or create a src/pages/404.astro page that Astro serves automatically.

Health checks work out of the box for web services. Render pings your service and restarts it if it becomes unresponsive:

// src/pages/health.ts (for SSR sites)
import type { APIRoute } from "astro";

export const GET: APIRoute = async () => {
  return new Response(JSON.stringify({ status: "ok" }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
};

Production Tips

1. Use Render's free static hosting for blogs. Static Astro sites deploy for free on Render. The free Hobby workspace includes a fixed monthly outbound-bandwidth allowance rather than unlimited transfer, and traffic beyond it is billed per GB, so check Render's current pricing if you expect heavy traffic. This is still a great fit for blogs, documentation sites, and marketing pages.

2. Set up deploy hooks for CMS-triggered rebuilds. If you use a headless CMS, get a deploy hook URL from Render (under your service settings) and configure your CMS webhook to hit it whenever content changes. This triggers an automatic rebuild.

Common Errors and Fixes

The web service deploys but every request times out or returns a 502. This is almost always the host-binding issue. Astro's standalone Node server listens on localhost by default, and Render's router cannot connect to a process bound only to loopback. Set the HOST environment variable to 0.0.0.0 on the service (or in render.yaml). This is documented in Render's own Astro deployment guide as the required variable for dynamic Astro sites.

Static assets return 404 after you add an adapter. Once a single page is rendered on demand, Astro stops writing everything to dist and splits the output, placing the client bundle in dist/client and the server entry in dist/server. If your static site service still points its publish directory at dist, the assets are no longer there. Switch the publish directory to dist/client. Astro's official Render guide states this explicitly.

The build fails with an unsupported Node version. Astro 6 requires Node 22.12.0 or newer. Node 18 reached end of life on April 30, 2025 and Node 20 reached end of life on April 30, 2026, which is why support for both was dropped. If Render picks an older runtime, pin a supported version with a .nvmrc file containing 22.12.0 or a NODE_VERSION environment variable.

You set output: "hybrid" and the build errors out. That mode was removed in Astro 5 and does not exist in Astro 6. You do not need it. Mixing static and on-demand pages is now the default behavior once an adapter is installed; control it per route with export const prerender = true or export const prerender = false.

render.yaml static-site service is rejected for a missing publish path. In a Blueprint, a static site uses type: web together with runtime: static, and the required field is staticPublishPath (for example ./dist). It does not take a startCommand. A web service, by contrast, uses runtime: node with buildCommand and startCommand.

Sharp or image-optimization errors during the build. Astro's built-in image optimization depends on sharp. If the install step prunes it or the platform lacks a prebuilt binary, add sharp to your dependencies and confirm your build command runs npm install (or your package manager's equivalent) before astro build.

Official Docs and Examples

• Astro's official Render deployment guide: https://docs.astro.build/en/guides/deploy/render/
• Render's Astro deployment guide: https://render.com/docs/deploy-astro
• Astro on-demand rendering guide (output modes and prerender): https://docs.astro.build/en/guides/on-demand-rendering/
• @astrojs/node adapter reference: https://docs.astro.build/en/guides/integrations-guide/node/
• Render Blueprint (render.yaml) reference: https://render.com/docs/blueprint-spec
• Working example repo, Render's official Astro SSR template source: https://github.com/render-examples/astro-ssr
• One-click Astro SSR template on Render: https://render.com/templates/astro-ssr

Alternatives to Consider

• Vercel if you want zero-config Astro deployment with edge functions and image optimization built in.
• Netlify if you need a similar experience with more built-in features like form handling and identity management.
• Railway if you need databases and background workers alongside your Astro site in a single platform.

Wrapping Up

Render is a clean, no-nonsense hosting platform that works well for both static and SSR Astro sites. The free tier for static sites is genuinely useful, not just a marketing gimmick, and the paid web services are reasonably priced for SSR deployments. The interface stays out of your way, deploys are fast, and the infrastructure-as-code option with render.yaml keeps your deployment config versioned alongside your application code. If you want straightforward hosting without the complexity of AWS or the vendor-specific features of Vercel, Render is a solid middle ground.

Sources

All versions and facts below were checked on 2026-05-29.

• Astro latest version (6.4.2): https://registry.npmjs.org/astro/latest
• @astrojs/node latest version (10.1.2, peer dependency astro ^6.3.0): https://registry.npmjs.org/@astrojs/node/latest
• Astro v6 upgrade guide, Node 22.12.0 minimum requirement: https://docs.astro.build/en/guides/upgrade-to/v6/
• Astro on-demand rendering guide, static default, server mode, and prerender per-route control: https://docs.astro.build/en/guides/on-demand-rendering/
• Astro Node adapter reference, npx astro add node, standalone vs middleware, HOST/PORT env vars, dist/server/entry.mjs: https://docs.astro.build/en/guides/integrations-guide/node/
• Astro official Render deploy guide, build command, publish directory dist vs dist/client: https://docs.astro.build/en/guides/deploy/render/
• Render official Astro deployment guide, HOST=0.0.0.0 requirement and adapter usage: https://render.com/docs/deploy-astro
• Render Blueprint YAML reference, runtime: static, staticPublishPath, web service fields: https://render.com/docs/blueprint-spec
• Render official Astro SSR example repository: https://github.com/render-examples/astro-ssr