Beginner8 minutesUpdated 2026-03-01

Astro is a modern web framework that ships zero JavaScript by default and uses an islands architecture for interactive components. Netlify provides excellent support for Astro, whether you're building a fully static site or using server-side rendering with the @astrojs/netlify adapter.

Prerequisites

Node.js 18 or later installed
An Astro project
A Netlify account
Git repository (GitHub, GitLab, or Bitbucket)

Step 1: Install the Netlify adapter (for SSR)

If you want server-side rendering, install the official Netlify adapter. For static-only sites, you can skip this step.

npx astro add netlify

The 'astro add' command automatically updates your astro.config.mjs with the correct adapter configuration.

Step 2: Configure your Astro project

For SSR, verify your astro.config.mjs uses the Netlify adapter. For static sites, the default configuration works out of the box.

astro.config.mjs

import { defineConfig } from 'astro/config'
import netlify from '@astrojs/netlify'

export default defineConfig({
  output: 'server',
  adapter: netlify(),
})

Step 3: Push to Git and connect to Netlify

Push your project to GitHub, GitLab, or Bitbucket. In Netlify, click 'Add new site' > 'Import an existing project' and select your repository.

Build settings

Build command: astro build
Publish directory: dist

Step 4: Set environment variables

Add any environment variables your project needs in Netlify's dashboard under Site settings > Environment variables. In Astro, public variables must be prefixed with PUBLIC_.

PUBLIC_API_URL=https://api.example.com
CMS_API_KEY=your-secret-key

Step 5: Deploy

Click 'Deploy site'. Netlify detects Astro automatically and builds your site. Static sites deploy to the CDN, while SSR sites use Netlify Functions for server-rendered pages.

netlify.toml Configuration

For static Astro sites, this is all you need. The Netlify adapter handles SSR configuration automatically when installed.

netlify.toml

[build]
  command = "astro build"
  publish = "dist"

Common Errors

Cannot find package '@astrojs/netlify'

Cause: The Netlify adapter isn't installed in your project dependencies.

Fix: Run 'npx astro add netlify' to install and configure the adapter automatically.

Error: The output directory 'dist' does not exist

Cause: The build command failed silently or the publish directory is misconfigured.

Fix: Verify your build command is 'astro build' and the publish directory is 'dist'. Check the build logs for any errors during compilation.

504 Gateway Timeout on SSR pages

Cause: Server-rendered pages are taking too long to respond, exceeding Netlify Functions' 10-second timeout.

Fix: Optimize your data fetching, add caching headers, or consider using static generation with 'output: hybrid' for pages that don't need real-time data.

Pro Tips

Use Astro's 'output: hybrid' mode to mix static and server-rendered pages — get the best of both worlds on Netlify.

Astro's zero-JS default makes it perfect for content-heavy sites on Netlify's CDN. Your pages load instantly.

Use Netlify's deploy previews to test Astro SSR changes before they go live.

Monitor your Astro site's deploy status with the Netli.fyi app — catch build failures immediately.

For large Astro sites, enable Netlify's build caching to speed up subsequent deploys significantly.

Deploy Astro to Netlify