How to Use Cloudflare Pages with Astro: Complete Guide

Cloudflare Pages is a serious contender for deploying Astro sites. You get unlimited bandwidth on the free tier, a global edge network spanning 300+ cities, and built-in support for server-side rendering through Cloudflare Workers. If you want fast deploys with zero bandwidth bills, this is the way to go.

Prerequisites

• Node.js 18+
• An Astro project (npm create astro@latest)
• A Cloudflare account (free at cloudflare.com)
• Your project in a Git repository (GitHub or GitLab)

Installation

Add the official Cloudflare adapter:

npx astro add cloudflare

This installs @astrojs/cloudflare and updates your config.

Configuration

After installation, your config will look like this:

// astro.config.mjs
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  output: "hybrid",
  adapter: cloudflare(),
});

For a purely static site, you can skip the adapter entirely. Just connect your repo to Cloudflare Pages in the dashboard and set the build command to npm run build with the output directory as dist.

Deploying to Cloudflare Pages

1. Go to your Cloudflare dashboard and select Pages
2. Click "Create a project" and connect your Git repository
3. Set the build settings:
   • Build command: npm run build
   • Build output directory: dist
4. Add any environment variables your project needs
5. Click "Save and Deploy"

Every push to your main branch triggers a production deployment. Pull requests get preview deployments automatically.

Basic Usage

With the adapter installed, server-rendered pages run on Cloudflare Workers at the edge:

---
// src/pages/api/data.ts
// This runs on Cloudflare Workers
export const prerender = false;

import type { APIRoute } from "astro";

export const GET: APIRoute = async ({ request }) => {
  const url = new URL(request.url);
  const country = request.headers.get("cf-ipcountry") || "unknown";

  return new Response(
    JSON.stringify({
      message: `Hello from the edge!`,
      country,
      timestamp: Date.now(),
    }),
    {
      headers: { "Content-Type": "application/json" },
    }
  );
};

Using Cloudflare Bindings

Cloudflare Pages lets you access KV storage, D1 databases, and R2 object storage through bindings. Access them via the Astro runtime:

// src/pages/api/visits.ts
import type { APIRoute } from "astro";

export const prerender = false;

export const GET: APIRoute = async ({ locals }) => {
  const runtime = locals.runtime;
  const kv = runtime.env.MY_KV_NAMESPACE;

  const visits = parseInt((await kv.get("visits")) || "0") + 1;
  await kv.put("visits", visits.toString());

  return new Response(JSON.stringify({ visits }), {
    headers: { "Content-Type": "application/json" },
  });
};

To use bindings locally during development, create a wrangler.toml file:

# wrangler.toml
name = "my-astro-site"
compatibility_date = "2026-02-01"

[[kv_namespaces]]
binding = "MY_KV_NAMESPACE"
id = "your-kv-namespace-id"

Production Tips

1. Take advantage of unlimited bandwidth. Unlike Vercel and Netlify, Cloudflare Pages has no bandwidth caps on the free tier. This makes it ideal for image-heavy or high-traffic sites.

Alternatives to Consider

• Vercel if you need advanced features like ISR (Incremental Static Regeneration) or prefer the Vercel developer experience and ecosystem.
• Netlify if you want built-in form handling, identity management, and a wider plugin ecosystem.
• Railway if you need a backend with databases alongside your static site, all in one platform.

Wrapping Up

Cloudflare Pages gives you an edge-first deployment platform with a generous free tier that is hard to beat. The official Astro adapter makes SSR seamless, and Cloudflare's binding system lets you add databases, KV storage, and object storage without leaving the ecosystem.