How to Deploy Astro to Netlify
The Real 2025 Guide (From Hard-Won Lessons)

1. The One Setting That Matters Most

Netlify still uses Node 18 by default (as of Dec 2025). Astro 5 wants Node 22 → build fails.

Fix It Forever (Recommended)

Create a file called .nvmrc in your project root:

This tells Netlify: “Use Node 18” → works 100% of the time.

Alternative: Netlify UI Method

Dashboard → Site Settings → Build & Deploy → Environment

Add variable:

NODE_VERSION = 18

Then delete any old NODE_VERSION vars.

2. Final Netlify Settings (Copy-Paste These)

Build Command

npm run build

Publish Directory

dist

Base Directory

(leave blank)

3. Secrets Scanning? (If Deploy Fails)

Netlify blocks deploys if it finds API keys in public/ files.

Fix: Remove old Google Analytics keys

Search your public/ folder for AIza or UA- and delete those lines/files.

4. Final Checklist Before Push

Do you have .nvmrc with "18"?

Is dist/ in .gitignore?

# .gitignore
dist/
node_modules/

No old API keys in public/?

You’re now 100% deploy-proof

One git push → 30 seconds → your Astro site is live on Netlify
No more Node version hell. Ever.

Built from real pain in December 2025 — so you don’t have to suffer.

Moving a site that already lives on someone else’s account: put it on your own GitHub and Netlify. Use the Node version that repository asks for. The 18 pin above is the December 2025 note.

How to Deploy Astro to NetlifyThe Real 2025 Guide (From Hard-Won Lessons)