How to Deploy an Astro Site to Cloudflare Pages

Cloudflare Pages gives you free, fast, global hosting for static sites — and Astro builds to exactly the kind of static output it loves. In this guide you’ll connect a repository and ship a live site in under ten minutes.

Before you start

You’ll need three things:

• An Astro project that builds locally (npm run build succeeds).
• A free Cloudflare account.
• Your code pushed to a GitHub or GitLab repository.

Step 1: Confirm your build command

Cloudflare needs to know how to build your site. For a standard Astro project the defaults are:

• Build command: npm run build
• Build output directory: dist

If you use Pagefind for search, your build script should run it after Astro:

{
  "scripts": {
    "build": "astro build && pagefind --site dist"
  }
}

Step 2: Create the Pages project

1. In the Cloudflare dashboard, go to Workers & Pages → Create → Pages.
2. Choose Connect to Git and authorize your repository.
3. Select the repo and branch (usually main).

Framework preset

Cloudflare detects Astro automatically and fills in the build command and output directory. Double-check they match Step 1, then click Save and Deploy.

Step 3: Watch the first build

Cloudflare clones your repo, installs dependencies, runs your build command, and uploads dist/ to its edge network. The first build takes a minute or two; subsequent builds are faster thanks to caching.

When it finishes you’ll get a URL like your-project.pages.dev. That’s your live site.

Step 4: Push to deploy

From now on, every push to your production branch triggers an automatic build and deploy. Pull requests get their own preview URLs, so you can review changes before they go live.

Step 5: Add a custom domain (optional)

In your Pages project, open Custom domains → Set up a custom domain, enter your domain, and follow the DNS prompts. If your domain already uses Cloudflare’s nameservers, the records are added for you and HTTPS is provisioned automatically.

Troubleshooting

• Build fails on Node version: set a NODE_VERSION environment variable (e.g. 20) in your Pages settings.
• 404s on routes with trailing slashes: make sure your trailingSlash config in astro.config.mjs matches how you link internally.

Frequently asked questions

Is Cloudflare Pages free? Yes — the free plan covers unlimited static requests and bandwidth, with generous build minutes. Most blogs and marketing sites never leave it.

Do I need Cloudflare Workers for a static Astro site? No. Pages serves static output directly. You only reach for Workers (or Astro’s SSR adapter) when you need server-side rendering or API routes.

How do I add a custom domain? In your Pages project, open Custom domains → Set up a custom domain. If the domain already uses Cloudflare’s nameservers, the DNS record and HTTPS certificate are provisioned for you automatically.

Can I preview pull requests before merging? Yes — every PR gets its own unique preview URL, so you can review changes in a real environment before they reach production.

That’s it — you now have a production site that redeploys on every push, served from hundreds of locations worldwide.