How to Deploy Astro to Netlify: Step-by-Step Guide

To deploy an Astro project to Netlify, first build your project locally using npm run build. Then, connect your GitHub repository to Netlify, set the build command to npm run build, and the publish directory to dist. Netlify will automatically build and deploy your site on each push.

Syntax

Deploying Astro to Netlify involves these key parts:

• Build Command: The command Netlify runs to build your site, usually npm run build.
• Publish Directory: The folder Netlify serves as your website, which is dist for Astro.
• Repository Connection: Linking your GitHub (or GitLab/Bitbucket) repo to Netlify for automatic deployment.

toml

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

Example

This example shows how to prepare your Astro project and deploy it to Netlify using GitHub:

• Initialize your Astro project and push it to GitHub.
• In Netlify, create a new site from Git and connect your GitHub repo.
• Set the build command to npm run build and publish directory to dist.
• Netlify will build and deploy your site automatically.

bash

npm init astro@latest my-astro-site
cd my-astro-site
npm install
npm run build

# Push to GitHub
# Then in Netlify UI:
# Build command: npm run build
# Publish directory: dist

Output

✔ Astro build completed
✔ Site deployed at https://your-site.netlify.app

Common Pitfalls

Common mistakes when deploying Astro to Netlify include:

• Not setting the publish directory to dist, causing Netlify to serve an empty site.
• Forgetting to run npm install before build, leading to build errors.
• Not committing the package.json or package-lock.json, so dependencies are missing on Netlify.
• Using an outdated Node.js version on Netlify; Astro requires Node.js 16 or higher.

toml

Wrong netlify.toml:
[build]
  command = "npm run build"
  publish = "public"

Correct netlify.toml:
[build]
  command = "npm run build"
  publish = "dist"

Quick Reference

Summary tips for deploying Astro to Netlify:

• Always set publish = "dist" in netlify.toml or Netlify UI.
• Use npm run build as the build command.
• Ensure your repo includes package.json and lock files.
• Check Node.js version compatibility in Netlify settings.
• Use Netlify's deploy logs to debug build issues.

Key Takeaways

Set Netlify build command to 'npm run build' and publish directory to 'dist' for Astro projects.

Connect your Git repository to Netlify for automatic builds on each push.

Ensure Node.js version on Netlify is 16 or higher to avoid build errors.

Include all dependency files like package.json and package-lock.json in your repo.

Use Netlify deploy logs to troubleshoot common build and deployment issues.