Astro deployment guide: zero-ops edge publishing with Cloudflare Pages
Git-driven Astro deployment in practice: commit to build, atomic publish to every edge node.
On this page
Quick answer
Why are my Astro component interactions not working?
By default components are zero-JS pure HTML. Add an explicit client:* directive (client:load, client:visible, etc.) on any interactive component, otherwise its script is never bundled into the page.
Machine-readable page data: /data/astro-deployment-guide.json
In-depth analysis
Astro's Islands Architecture ships zero client-side JavaScript by default and pushes first-paint performance to the limit; content sites use it to pre-render static HTML at build time and serve it directly from edge nodes. At deploy time hand the built artifact to the edge platform and lean on static fallback plus security headers to hold the line on stability.
// astro.config.mjs — static SSG + Cloudflare Pages edge delivery
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
site: 'https://aicode8.com',
output: 'static',
vite: { plugins: [tailwindcss()] },
});Astro Deployment Guide · Key takeaways
- astro.config has a single source-of-truth site value
- public/_headers declares nosniff and HSTS
- 404 returns a real 404
- Preview passes all 8 edge drills
FAQ & pitfalls
How do I invalidate cache after deploying an Astro static site to Cloudflare Pages?
Each git commit triggers an atomic rebuild that replaces the full static output as a whole. Set HTML to must-revalidate and static assets to immutable long cache — no manual CDN purge required.
Explore the hub
See all 5 guides in Hands-onSame category as this article, sorted across the codebase.
Astro best practices: engineering conventions for production
Field-tested Astro practices from production, avoiding the common anti-patterns.
Astro performance tuning: push first paint and edge response to the limit
Around Astro's real bottlenecks, an actionable LCP / INP / CLS checklist.
Astro hands-on tutorial: from zero to your first runnable project
Step-by-step walkthrough of Astro with copy-paste commands, directory layout, and a first runnable artifact.
Cloudflare Pages best practices: engineering conventions for production
Field-tested Cloudflare Pages practices from production, avoiding the common anti-patterns.
Share & save
What readers are asking
Questions that keep coming back in reader feedback, already answered.
- 01
Why is my Astro component's interactivity not working?
Components ship as zero-JS HTML by default, so an interactive one needs a client:* directive (client:load, client:visible, …). Without it the script is never bundled into the page.
See the full guide → - 02
Which Astro version supports the @tailwindcss/vite integration reliably?
Astro 5 and later officially recommend the @tailwindcss/vite plugin over the old PostCSS route. Pin the astro and tailwind major versions before upgrading, or the new plugin silently ignores your v3 config.
See the full guide → - 03
Why is my custom Tailwind v4 brand colour not applied?
Colours must be declared in @theme (for example --color-brand). A missing @tailwindcss/vite plugin, or a leftover v3 config, makes bg-brand silently render nothing.
See the full guide →