Deploy to Netlify

What Is Netlify?

Netlify is a static hosting platform that has offered automatic Astro support with zero configuration since the early days of the framework . For Astro Docus, Netlify is a strong choice because:

• Automatic framework detection — Netlify recognizes Astro and pre-fills the correct build settings
• Free tier with generous bandwidth and build minutes
• Preview deployments for every pull request
• One-click rollbacks from the dashboard
• Built-in form handling (useful if you later replace Formspree)

The official Netlify documentation recommends the Astro adapter for projects that use server-side features or the <Image /> component with Netlify Image CDN. However, for a fully static site like Astro Docus — which is the default output — the adapter is not required .

Note for Astro Docus users: The template ships with a Cloudflare adapter in astro.config.mjs. Before deploying to Netlify, either remove the adapter block for a static deploy, or switch to the Netlify adapter if you need server features.

---

Prerequisites

Before starting, you need:

• A Netlify account (free)
• Your Astro Docus project pushed to GitHub (see the previous guide)
• A terminal open in your project folder (for the CLI method)

---

Method 1 — Deploy via GitHub Integration

This is the recommended method. Once set up, every push to your main branch triggers an automatic production deploy .

Step 1 — Sign Up or Log In to Netlify

1. Go to: https://app.netlify.com/signup
2. Click Sign up with GitHub (recommended) or use email
3. Authorize Netlify to access your GitHub account
4. Complete the onboarding flow

Using GitHub as your sign-in method simplifies the connection later.

Step 2 — Create a New Site

1. After logging in, you land on the Netlify dashboard
2. Click Add new project → Import an existing project
3. You are prompted to connect a Git provider
4. Select GitHub

Step 3 — Authorize GitHub

1. Netlify opens a GitHub authorization page
2. You can grant access to:
   • All repositories (simpler)
   • Only select repositories (recommended for security)
3. Select your Astro Docus repository
4. Click Install & Authorize

Step 4 — Select the Repository

1. Netlify shows a list of your GitHub repositories
2. Click on your Astro Docus repository

Step 5 — Configure Build Settings

Netlify automatically detects Astro and pre-fills the correct settings . Verify they match:

Configuration option	Value
Build command	npm run build (or astro build)
Publish directory	dist
Node version	20 (recommended)

These settings match the official Astro deployment guide .

Tip: If you want to lock these settings permanently, create a netlify.toml file in your project root:

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

This file ensures consistent builds even if the dashboard settings are changed .

Step 6 — Deploy

1. Click Deploy site
2. Netlify begins building your site
3. You see a build log with each step
4. First build takes 1–3 minutes
5. When complete, you receive a random subdomain

Step 7 — Your Live Site

After deployment, your site is live at:

https://random-name-12345.netlify.app

You can customize the subdomain to something memorable:

1. Go to Site configuration → Domain management
2. Click Options next to the default URL
3. Click Edit site name
4. Enter your preferred name
5. The URL updates automatically

Automatic Deployments

Once connected, every push triggers a deploy :

Action	Result
Push to main	Production deploy
Push to another branch	Branch deploy (if enabled)
Open a pull request	Deploy Preview with unique URL

This means you never manually deploy again. Just git push, and Netlify handles the rest.

---

Method 2 — Deploy via Drag and Drop (Netlify Drop)

Netlify Drop is the fastest way to get a site online without connecting Git . You build locally and drag the output folder to the browser.

Important: When logged in, Netlify can detect your framework and run the build for you. If you are not logged in, files are published exactly as they are — so you must build locally first .

Step 1 — Build Your Site Locally

npm run build

This generates the dist/ folder.

Step 2 — Open Netlify Drop

1. Go to: https://app.netlify.com/drop
2. If you are not logged in, you can still drop a folder — but you will need to claim the site within one hour

Step 3 — Drag Your Folder

1. Open your project folder in File Explorer or Finder
2. Drag the dist folder into the Netlify Drop zone
3. Netlify uploads the files and publishes them

What to drag: The dist folder — this is the pre-built output containing index.html, CSS, JS, and assets .

Step 4 — Your Live Site

After upload, your site is live at:

https://random-name-12345.netlify.app

You can rename it the same way as the Git method.

Updating a Dropped Site

To update a site published with Netlify Drop:

1. Run npm run build again locally
2. Go to your project dashboard on Netlify
3. Scroll to Production deploys
4. Drag the updated dist folder into the drop zone
5. The new files become the latest production version

---

Method 3 — Deploy via Netlify CLI

Use this method if you prefer the command line or want to test builds locally before deploying.

Step 1 — Install Netlify CLI

npm install --global netlify-cli

Step 2 — Log In

netlify login

This opens your browser. Log in and authorize the CLI.

Step 3 — Initialize the Project

netlify init

The CLI detects Astro and offers to:

• Create a new Netlify site
• Link to an existing site

It also offers to generate a netlify.toml file with the correct build settings .

Step 4 — Deploy

For a preview deploy (temporary URL):

netlify deploy

For a production deploy:

netlify deploy --prod

Step 5 — Your Live Site

The CLI outputs your live URL after deployment.

Note: Manual CLI deploys do not run the build command by default. You must run npm run build first, then deploy the dist folder .

---

Adding a Custom Domain

A *.netlify.app subdomain works, but a custom domain looks more professional.

Step 1 — Go to Domain Management

1. In the Netlify dashboard, click your project
2. Go to Site configuration → Domain management

Step 2 — Add Domain

1. Click Add a domain
2. Enter your domain (e.g., docs.yourdomain.com)
3. Click Verify

Step 3 — Configure DNS

Netlify shows the required DNS records. Go to your domain registrar and add:

Record Type	Name	Value
A	@ (root)	Netlify’s load balancer IP (75.2.60.5)
CNAME	www or subdomain	your-site.netlify.app

Step 4 — Enable HTTPS

Netlify automatically provisions a free SSL certificate via Let’s Encrypt once DNS propagates . HTTPS is enabled by default.

Step 5 — Verify

After DNS propagation (usually minutes, sometimes hours), your custom domain works with HTTPS automatically.

---

Netlify Configuration File (Optional)

Create netlify.toml at your project root for consistent builds:

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

[build.environment]
  NODE_VERSION = "20"

This file ensures every build uses the same settings, regardless of dashboard configuration .

---

Troubleshooting

Problem	Likely Cause	Fix
Build fails	Missing dependencies	Run npm install locally, commit package-lock.json
404 errors	Missing index.html at root	Ensure dist/index.html exists
Site works locally but not on Netlify	Missing site URL	Set site in astro.config.mjs
Netlify Drop site disappears	Not claimed within 1 hour	Create an account and claim the site
Custom domain not working	DNS not propagated	Wait, or verify records
Images not loading	Wrong paths	Use /src/assets/ paths or public/ folder
Build times out	Large node_modules	Add .netlify to .gitignore

---

Environment Variables (Optional)

If your project needs environment variables, set them in:

Netlify Dashboard → Site configuration → Environment variables

Common variables for Astro Docus:

Variable	Value	Purpose
NODE_VERSION	20	Ensures correct Node.js version
PUBLIC_SITE_URL	https://yourdomain.com	Canonical URL

Warning: Never commit secrets to netlify.toml. That file is in your repository. Use the dashboard for sensitive values .

---

Quick Recap

Method 1 — GitHub Integration (recommended):
1. Sign up at netlify.com with GitHub
2. Add new project → Import existing project
3. Select GitHub → Authorize → Choose repo
4. Verify build settings (auto-detected)
5. Click Deploy
6. Live at *.netlify.app

Method 2 — Netlify Drop:
1. npm run build locally
2. Go to app.netlify.com/drop
3. Drag the dist folder
4. Live at *.netlify.app

Method 3 — Netlify CLI:
1. npm install -g netlify-cli
2. netlify login
3. netlify init
4. netlify deploy --prod

Custom Domain:
- Dashboard → Domain management
- Add domain → Configure DNS
- HTTPS automatic

Free Tier:
- 100 GB bandwidth/month
- 300 build minutes/month
- Unlimited sites

Netlify is zero-config for Astro static sites. Once connected to GitHub, every git push deploys your site globally with preview URLs for every pull request.

👉 Next: docs/deploy-hosting/firebase.md — deploy to Firebase Hosting.