How to Deploy an Astro Site: Vercel, Netlify & Cloudflare

Introduction

One of the best things about Astro is how easy it is to put online. A static Astro site is just a folder of HTML, CSS, and assets, so you can host it almost anywhere, usually for free. This guide walks through deploying an Astro site to Vercel, Netlify, Cloudflare, and GitHub Pages, then covers custom domains, environment variables, and the build errors people hit most often.

The steps work for any Astro project, whether you started from npm create astro@latest or from a ready-made Astro theme.

Before You Deploy

A few minutes of preparation saves most deployment headaches.

1. Make sure the build works locally

npm install
npm run build
npm run preview

npm run build writes your site to the dist/ folder, and npm run preview serves it locally so you can click through the production version before anyone else does. If the build fails here, it will fail on your host too.

2. Set your site URL

Open astro.config.mjs and set site to the final address of your website:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://www.example.com',
});

Astro uses this value to build absolute URLs for canonical tags, sitemaps, and RSS feeds. Leaving the placeholder in place is a common SEO mistake.

3. Push your project to Git

All the hosts below deploy automatically from a Git repository on GitHub, GitLab, or Bitbucket. Push your project, and every future git push will publish a new version of your site.

4. Static or server?

By default Astro builds a static site, and that is all most blogs, portfolios, and marketing sites need. If you render pages on demand (for example with output: 'server'), you also need your host's adapter. Each section below shows the one-line command to add it.

Deploy Astro to Vercel

1. Sign in to Vercel and choose Add New → Project.
2. Import your Git repository.
3. Vercel detects Astro automatically and fills in the build command (npm run build) and output directory (dist). Leave them as they are.
4. Click Deploy.

A minute later your site is live on a *.vercel.app address, and every push to your main branch redeploys it. Pull requests get their own preview URLs.

Prefer the command line?

npx vercel        # deploy a preview
npx vercel --prod # deploy to production

Need server rendering? Add the adapter:

npx astro add vercel

Deploy Astro to Netlify

1. In Netlify, choose Add new site → Import an existing project.
2. Connect your Git provider and pick the repository.
3. Set the build command to npm run build and the publish directory to dist (Netlify usually fills these in for Astro).
4. Click Deploy.

You can also keep the settings in your repository with a netlify.toml file:

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

Or deploy from the command line with the Netlify CLI:

npx netlify-cli deploy --prod --dir=dist

Need server rendering? Add the adapter:

npx astro add netlify

Deploy Astro to Cloudflare

Cloudflare serves static sites from its global network, which makes it one of the fastest free options.

1. In the Cloudflare dashboard, open Workers & Pages and create a new application.
2. Connect your Git repository.
3. Set the build command to npm run build and the output directory to dist.
4. Save and deploy.

To deploy from the command line with Wrangler, add a wrangler.jsonc file that points at your build output:

{
  "name": "my-astro-site",
  "compatibility_date": "2026-10-01",
  "assets": {
    "directory": "./dist"
  }
}

Then build and deploy:

npm run build
npx wrangler deploy

Need server rendering? Add the adapter:

npx astro add cloudflare

Deploy Astro to GitHub Pages

GitHub Pages is a good free option for personal sites and open-source project pages.

1. In astro.config.mjs, set site to https://<username>.github.io. If the site lives in a repository subfolder rather than at the root, also set base: '/<repository-name>'.
2. Add a workflow file at .github/workflows/deploy.yml that uses Astro's official GitHub Action:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: withastro/action@v3

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

3. In your repository settings, open Pages and set the source to GitHub Actions.

Every push to main now builds and publishes the site. Check Astro's deployment docs for the latest action versions.

Which Host Should You Choose?

For a static site you cannot go wrong with any of them. Choose the dashboard you like, or the platform your team already uses.

Add a Custom Domain

1. Open your project's Domains settings on your host and add your domain, for example www.example.com.
2. The host shows the DNS records to create, usually a CNAME for www and an A or ALIAS record for the root domain.
3. Add those records at your domain registrar. Changes usually take effect within minutes, occasionally up to a day.
4. HTTPS certificates are issued automatically once DNS resolves.

Pick one version of your domain, with or without www, redirect the other to it, and make sure it matches the site value in astro.config.mjs.

Environment Variables

Never commit API keys to Git. Instead, add them in your host's dashboard under Environment Variables, and in a local .env file for development (add .env to .gitignore).

In Astro, variables are private to the server by default. Only variables prefixed with PUBLIC_ are exposed to code that runs in the browser:

# .env
PUBLIC_SITE_NAME="My Site"   # available in the browser
NEWSLETTER_API_KEY="secret"  # server and build time only

Read them with import.meta.env.PUBLIC_SITE_NAME. Remember to redeploy after changing variables on your host, because static sites read them at build time.

Common Deployment Errors and Fixes

Unsupported Node.js version. Recent Astro versions need a recent Node.js (Astro v7 projects typically require Node.js 22.12 or newer). Set the Node.js version in your host's build settings or with an engines field in package.json:

{
  "engines": {
    "node": ">=22.12.0"
  }
}

Works locally, fails on the server with "module not found". Build servers run Linux, which is case-sensitive. An import of ./components/Header.astro fails if the file is actually named header.astro. Make import paths match file names exactly.

Missing environment variable. If the build log mentions undefined where an API key should be, add the variable in the host dashboard and redeploy.

404 on page refresh or wrong asset paths on GitHub Pages. Check that site and base in astro.config.mjs match where the site is actually served.

Images missing after deploy. Files in public/ are served from the site root, so public/images/logo.png is available at /images/logo.png. Images imported from src/ are processed by astro:assets; import them in your component instead of linking to them by path.

After You Go Live

• Submit your sitemap (usually /sitemap-index.xml with @astrojs/sitemap) in Google Search Console. Our Astro SEO guide covers the rest of the technical SEO setup.
• Run PageSpeed Insights on your homepage and a few key pages.
• Turn on your host's analytics, or add a privacy-friendly analytics script.
• Set up a branch workflow so changes get a preview URL before they reach production.

Frequently Asked Questions

Where is the best place to host an Astro site?

For a static Astro site, Vercel, Netlify, and Cloudflare are all excellent and have generous free plans. Pick the one whose dashboard you prefer or that you already use. If you need on-demand server rendering, choose the platform whose Astro adapter matches the features you need.

Is hosting an Astro site free?

A static Astro site can usually be hosted for free on Vercel, Netlify, Cloudflare, or GitHub Pages. Paid plans are only needed for heavy traffic, team features, or advanced server features.

Do I need an adapter to deploy Astro?

No, not for a static site. Run npm run build and upload the dist folder. You only need an adapter, such as @astrojs/vercel, @astrojs/netlify, @astrojs/cloudflare, or @astrojs/node, when you render pages on demand on the server.

Why does my Astro build fail on the host but work locally?

The most common causes are an older Node.js version on the host, a missing environment variable, and file name case mismatches that only show up on Linux build servers. Set the Node.js version to match your local machine, add your environment variables in the host dashboard, and check that import paths match file names exactly.

How do I connect a custom domain to my Astro site?

Add the domain in your host's dashboard, then create the DNS records it shows you at your domain registrar. HTTPS certificates are issued automatically. Remember to set the site option in astro.config.mjs to your final domain so canonical URLs and sitemaps are correct.

Conclusion

Deploying Astro takes minutes: build locally, push to Git, connect your repository to Vercel, Netlify, Cloudflare, or GitHub Pages, and point your domain at it. From then on, every push publishes your site.

Need a site to deploy? Every Platoltheme Astro theme comes with step-by-step documentation that ends with a deployment section, so you can go from download to a live site in an afternoon. Not sure which one fits? Start with the best Astro themes for 2026.