netlify-frameworks-astro

Astro on Netlify

Setup

Check current versions before pinning. Knowledge cutoffs lag behind npm, and guessing a version tends to fail (npm install rejects it, or worse, installs something incompatible). Before pinning @astrojs/netlify, astro, or any other package in package.json, run npm view <pkg> version to get the current latest. Or omit explicit pins and let npm install pick them up. If that check itself fails (no network, registry unreachable), still don't fall back to a guessed exact pin — install without a version (or with @latest) and tell the user live verification wasn't possible so they should confirm the installed versions. Never present an unverified x.y.z as the current release.

Install the Netlify adapter:

npx astro add netlify

This installs @astrojs/netlify and updates astro.config.* automatically.

Manual Setup

npm install @astrojs/netlify

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

export default defineConfig({
  output: "server",  // on-demand (SSR) by default; or "static" (the default) for prerendered
  adapter: netlify(),
});

Output Modes

Astro 5 removed the "hybrid" mode — there are now two output modes, and per-route control replaces it. Both modes need the adapter once any route renders on demand.

Mode	Behavior
"static" (default)	Prerendered (hybrid-by-default): pages are static HTML at build time. Opt individual routes into on-demand rendering with export const prerender = false.
"server"	On-demand (SSR) by default. Opt individual routes into prerendering with export const prerender = true.

What the Adapter Does

• Converts Astro server routes into Netlify Functions
• Handles SSR, API routes, and middleware
• Maps Astro's routing to Netlify's function routing
• You do not write raw Netlify Functions for Astro's server routes

API Routes

Astro API routes (in src/pages/api/) are handled by the adapter: