How to Use Netlify with Astro: Complete Guide

Netlify is one of the most popular platforms for deploying Astro sites, and for good reason. You get continuous deployment from Git, serverless functions, edge computing, and a generous free tier. Astro has an official Netlify adapter, which means you can deploy both static and server-rendered Astro sites with minimal configuration.

I use Netlify for several Astro projects, and the deploy process is about as smooth as it gets. Push to Git, site builds automatically, preview deploys for pull requests. The whole workflow just works.

Prerequisites

• Node.js 18+
• An Astro project (npm create astro@latest)
• A Netlify account (free tier available)
• A Git repository (GitHub, GitLab, or Bitbucket)

Installation

For static Astro sites, you do not need any adapter. Just deploy. For SSR (server-rendered) Astro sites, install the official adapter:

npx astro add netlify

This installs @astrojs/netlify and updates your config automatically. For manual installation:

npm install @astrojs/netlify

Configuration

For a static site, your astro.config.mjs needs no changes. Astro's default output mode is "static", which Netlify handles natively.

For SSR or hybrid rendering:

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

export default defineConfig({
  output: "hybrid", // or "server" for full SSR
  adapter: netlify(),
});

Create a netlify.toml in your project root for build settings:

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "18"

[[redirects]]
  from = "/*"
  to = "/404"
  status = 404

Basic Usage

Connect your Git repository to Netlify through the Netlify dashboard:

1. Log in to Netlify and click "Add new site" > "Import an existing project"
2. Select your Git provider and repository
3. Set the build command to npm run build (or astro build)
4. Set the publish directory to dist
5. Add any environment variables your site needs
6. Click "Deploy site"

That is it. Netlify detects Astro automatically and handles the rest. Every push to your main branch triggers a new deploy.

For environment variables, add them in Netlify's dashboard under Site settings > Environment variables:

# Example variables you might need
PUBLIC_SITE_URL=https://your-site.netlify.app
CONTENTFUL_API_TOKEN=your_token_here

To use Netlify Functions alongside your Astro site, create a netlify/functions/ directory:

// netlify/functions/hello.ts
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Hello from Netlify Functions" }),
  };
};

This function becomes available at /.netlify/functions/hello.

Production Tips

1. Use deploy previews. Every pull request gets its own preview URL automatically. Share these with your team for review before merging. No extra configuration needed.

2. Set up custom headers for performance. Add a _headers file in your public/ folder to control caching. For static assets, set long cache times: Cache-Control: public, max-age=31536000, immutable.

3. Enable Netlify Edge Functions for dynamic features. If you need middleware, A/B testing, or geolocation-based content, use edge functions. They run on Netlify's edge network, close to your users.

4. Configure redirects properly. Use the netlify.toml or a _redirects file for URL redirects and rewrites. This is important when migrating from another platform to preserve your SEO equity.

5. Monitor build times. Netlify's free tier gives you 300 build minutes per month. For content-heavy sites with frequent updates, keep an eye on build times. Use Astro's incremental builds or limit rebuilds to content-change webhooks.

Alternatives to Consider

• Vercel if you want slightly faster builds and tighter integration with Next.js or other Vercel-optimized frameworks. Astro works well on both.
• Cloudflare Pages if you want unlimited bandwidth on the free tier and a global edge network with zero egress fees.
• Railway if your project needs a backend server alongside the frontend and you want everything on one platform.

Wrapping Up

Netlify and Astro is a battle-tested combination. The deployment process is effortless, the free tier is generous, and features like deploy previews and serverless functions cover most use cases without additional tooling. Whether you are running a static blog or a hybrid SSR application, Netlify handles Astro projects reliably.