Deploying Astro to Cloudflare Pages

Intro

Astro pairs nicely with Cloudflare Workers: the platform ships static assets, and a Worker can serve SSR. This walkthrough captures everything I need to deploy codetwine.dev onto Workers, including image optimization and dashboard weaks that make future deploys painless.

Prerequisites

• Astro project bootstrapped with pnpm create astro@latest or pnpm create cloudflare@latest my-astro-app --framework=astro --platform=pages
• PNPM 10+ and Node 22+
• Cloudflare account with Workers & Pages enabled
• Domain managed in Cloudflare (for custom routing)

Install dependencies

pnpm add @astrojs/cloudflare
pnpm add -D wrangler

@astrojs/cloudflare swaps the default adapter for a Worker-friendly build. wrangler provides local previews, deploy commands, and type generation.

Wire up package scripts

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro build && wrangler pages dev",
    "deploy": "astro build && wrangler pages deploy"
  }
}

• wrangler pages dev runs the Cloudflare runtime locally so you can catch Worker-only issues before shipping.

Update astro.config.mjs

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
    },
    imageService: 'passthrough',
  }),
  site: 'https://codetwine.dev',
});

• platformProxy.enabled mirrors Cloudflare bindings (KV, D1, R2, env vars) in dev.
• imageService: 'passthrough' build time image optimization. You can enable cloudflare cdn also
• site is required for absolute URLs, RSS feeds, and sitemap generation.

Add wrangler.jsonc

wrangler looks for configuration at the project root:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "codetwine",
  "compatibility_date": "2025-10-01",
  "compatibility_flags": ["nodejs_compat"],
  "observability": {
    "enabled": true
  },
  "pages_build_output_dir": "dist",
  "assets": {
    "directory": "dist",
    "not_found_handling": "404-page"
  }
}

• nodejs_compat unlocks familiar Node APIs inside the Worker runtime.
• observability.enabled exposes the Logs & Traces tab in the dashboard.
• pages_build_output_dir points Pages at the Astro build output.

Ignore Worker-only artifacts

Cloudflare auto-generates _worker.js and _routes.json. Tell Pages to skip them when syncing assets by adding public/.assetsignore:

_worker.js
_routes.json

Anything listed here stays out of your static bundle.

Push to GitHub

Cloudflare Pages expects a repository to watch. Commit the changes and push:

git add .
git commit -m "chore: prepare Cloudflare Pages deploy"
git push origin main

Configure Pages in the dashboard

1. Visit dash.cloudflare.com.
2. Navigate to Workers & Pages → Workers&Pages and choose Create application.
3. Pick Connect to Git and authorize your repo.
4. Fill out the build step:
   • Project name: codetwine
   • Framework preset: Astro
   • Build command: pnpm run build
   • Output directory: dist
   • Production branch: main
5. Save — Cloudflare will kick off the first deployment automatically.

Add a custom domain

1. In the Pages project, open Settings → Domains & Routes.
2. Click Set up a custom domain and choose a zone in your Cloudflare account.
3. Provide a route, e.g. codetwine.dev/*.
4. Wait for the DNS status to turn green; the proxy handles SSL automatically.

If the domain lives outside Cloudflare, add an A record for @ and www that points to Cloudflare and delegate nameservers before enabling the route.

Post-deploy checks

• Run Lighthouse against the production URL.

Summary

Once the Cloudflare adapter is wired in, Workers behaves like any other Astro deployment target—just faster at the edge. Keep wrangler in sync, lean on the dashboard for observability, and you can ship straight from commits to production with confidence.