Next.js deployment guide: zero-ops edge publishing with Cloudflare Pages
Git-driven Next.js deployment in practice: commit to build, atomic publish to every edge node.
On this page
Quick answer
Why does Next output:export fail to build?
Server-side data fetching on dynamic routes or middleware is not allowed. Images must be set to unoptimized, or the export aborts.
Machine-readable page data: /data/nextjs-deployment-guide.json
In-depth analysis
Next.js is the dominant React meta-framework. output:export produces pure static output, but the core engine here is still Astro — Next pages exist here only for comparison and traffic capture. 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.
// next.config.mjs — pure static export (no server functions)
const nextConfig = { output: 'export', images: { unoptimized: true } };
export default nextConfig;
// Build: next build && next exportNext.js 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 for Next static export?
The export is pure static files; atomically replace and use long cache for hash-named assets. HTML must-revalidate ensures the origin refreshes.
Explore the hub
See all 5 guides in Next.jsSame category as this article, sorted across the codebase.
Next.js architecture: layered patterns for high-concurrency edge apps
The edge-delivery view of Next.js's layering and data flow.
Next.js best practices: engineering conventions for production
Field-tested Next.js practices from production, avoiding the common anti-patterns.
Next.js performance tuning: push first paint and edge response to the limit
Around Next.js's real bottlenecks, an actionable LCP / INP / CLS checklist.
Next.js in practice: pure static export
Use output:export to ship Next.js as pure static files, capturing React ecosystem traffic without server-side dependencies.
Share & save
What readers are asking
Questions that keep coming back in reader feedback, already answered.
- 01
How do I fix a failing Next.js output: export build?
Server-side data fetching in dynamic routes, and middleware, both break the export; next/image also needs unoptimized or the export aborts.
See the full guide → - 02
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 → - 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 →