Headless Magento with Astro: The Complete Guide
Headless Magento with Astro: the complete guide
Headless Magento means separating the storefront customers see from the Magento that runs your business, and connecting the two over Magento's GraphQL API — and Astro is currently the most practical framework to build that storefront with, because it ships plain HTML by default and JavaScript only where a component genuinely needs it. Done well, this is how a Magento store passes Core Web Vitals as its normal state and bends fully to your brand; done for the wrong reasons, it adds cost and complexity you did not need. This guide covers both honestly.
The build described here is the front end of the AgenticEcom Suite, but the architecture is yours to copy whoever builds it.
What "headless" actually means
A traditional Magento store renders its pages with the built-in Luma theme — backend and frontend welded together in one application. A headless setup splits them. Magento Open Source becomes a pure backend, exposing catalogue, pricing, cart, customers and orders over its GraphQL API; a separate, modern frontend renders the actual pages and calls that API for data. Nothing about your admin, orders, stock or B2B logic changes. Only the shop window does.
| Traditional (Luma theme) | Headless (Astro) | |
|---|---|---|
| Who renders the page | Magento's PHP, per request | The frontend, mostly pre-rendered |
| JavaScript shipped | Large RequireJS layer on every page | Only the interactive islands (cart, search, checkout) |
| Where pages are served from | Your origin server | A CDN edge, close to the customer |
| Design freedom | Bound by theme structure | Anything the web can do |
| Admin, orders, B2B logic | Magento | Still Magento — unchanged |
Why Astro rather than PWA Studio or Next.js
The frontend framework decides most of the outcome, so choose it deliberately.
- Astro ships HTML by default and hydrates JavaScript only for the components you mark as interactive — its "islands" model. For a content-and-catalogue site, which is what every store is, that means fast pages are the starting position rather than an optimisation project.
- PWA Studio, Adobe's React-based headless frontend, is fully decoupled but carries a large JavaScript bundle and a steep maintenance burden — and Adobe's own frontend attention has since moved to its Edge Delivery storefront, leaving PWA Studio with little forward momentum.
- Next.js is a capable general-purpose framework, but it is JavaScript-first: you spend effort removing weight that Astro never adds in the first place.
The three-way comparison, including Hyvä as the non-headless alternative, is set out in headless Magento vs Hyvä vs PWA Studio.
The performance payoff
This is the point of the exercise. Because the storefront is pre-rendered HTML with minimal JavaScript, served from a CDN edge near the customer, the three Core Web Vitals are addressed structurally: LCP by fast delivery and edge-optimised images, INP by the near-absence of main-thread JavaScript, CLS by layouts built with space reserved. A live client store on this stack — a catalogue of over 1,000 products on Magento Open Source — passes all three Core Web Vitals in Google's field data, measured July 2026. Speed is not vanity here — it is a confirmed ranking input, a conversion lever, and increasingly what makes a store legible to automated buyers. The thresholds and how Google judges them are in Magento Core Web Vitals.
The stack that gets you there
| Layer | What we use |
|---|---|
| Backend | Magento Open Source 2.4.x, exposing the GraphQL API |
| Frontend | Astro — static pages plus interactive islands |
| Hosting | Cloudflare Pages, on the global edge |
| Images | Edge image delivery with AVIF/WebP negotiation |
| Freshness | Incremental regeneration — changed pages rebuilt and re-pushed on data change |
The Cloudflare half of this — proxy, cache rules, WAF, Pages — is covered step by step in Magento on Cloudflare.
How a headless build actually proceeds
- Audit your extensions for frontend coupling. Modules that only work in the admin carry over untouched; modules that inject Luma templates need a headless equivalent or an API route. This audit, more than anything technical, decides the size of the project — a store whose extensions are mostly admin-side can go headless with far less friction than one whose customer experience is built from frontend widgets.
- Stand up the API. Magento's GraphQL endpoint ships with 2.4.x; you configure CORS so the storefront's domain may call it, and verify catalogue, cart and customer queries return what the design needs.
- Build the page types. A store is a small set of templates — home, category, product, search, cart, checkout, account, CMS — each pre-rendered where possible and hydrated only where interactive. Checkout deserves the most care: it is the one flow that is unavoidably dynamic, so it is built as an island talking to Magento's cart and payment APIs while everything around it stays static.
- Wire up images. Product imagery routes through edge image delivery so format and size are negotiated per visitor rather than baked in.
- Deploy to the edge and connect invalidation, so a price change in Magento rebuilds only the affected pages. Without this step you choose daily between stale pages and slow ones.
- Measure before switchover. Run the new storefront against the Core Web Vitals thresholds and your own conversion journeys on a staging domain, then move DNS.
What happens to SEO when you go headless
Done properly, headless is an SEO upgrade rather than a risk, because pre-rendered HTML is exactly what crawlers want: complete pages with no client-side rendering for Googlebot to execute, faster Core Web Vitals feeding the ranking signal, and full control of titles, canonicals and structured data per template. The risks are all migration risks, not architecture risks. Keep your URL structure where you can; put permanent redirects on anything that must change; carry over metadata, hreflang and structured data deliberately rather than assuming the new frontend inherits them; and crawl the staging site with the same tools you would use on the live one before switching DNS. Stores that lose rankings after going headless almost always lost them at the migration step — changed URLs without redirects, or templates that shipped without the metadata the old theme had.
When NOT to go headless
Honest counsel, because headless is not free. Stay traditional if any of these describe you: a small store with no development resource and no partner; a frontend that depends on Luma-only extensions you cannot replace; or a business where "simple and good enough" genuinely beats "fast and flexible". A well-tuned conventional Magento store — or even a hosted platform — can be the right answer. Headless earns its keep when speed, brand control and multi-channel flexibility measurably matter to your revenue; it is a strategic choice, not a fashion.
The shortcut: don't assemble it yourself
Building this stack from scratch — the Astro storefront, the GraphQL plumbing, the headless support modules, the edge deployment and the Core Web Vitals tuning — is a serious project of the kind agencies quote in months. We built it once and packaged it: the AgenticEcom Astro storefront is a finished, no-code-editable headless front end, and the supporting headless module set ships pre-integrated, so the architecture in this guide arrives working rather than as a to-do list.
FAQ
Does going headless change my Magento admin or orders?
No. Headless replaces only the storefront. Your Magento admin, catalogue, customers, orders and B2B logic stay exactly as they are; the new frontend reads and writes them through the GraphQL API.
Why Astro instead of PWA Studio for headless Magento?
Astro ships HTML by default and loads JavaScript only for interactive components, so strong Core Web Vitals are the starting position rather than a tuning project. PWA Studio carries a large React bundle and a heavier maintenance load, and Adobe's frontend investment has moved on to its Edge Delivery storefront.
How fast can headless Magento actually be?
Fast enough to pass Google's bar as a matter of course: a live client store on this stack passes all three Core Web Vitals in Google's field data on a catalogue of over 1,000 products (measured July 2026). The speed comes from pre-rendered HTML, minimal JavaScript and edge delivery rather than from tuning.
Do my existing Magento extensions still work with a headless frontend?
Admin-side and backend modules carry over unchanged, because the Magento application itself is untouched. Modules that inject content into Luma templates need a headless-aware equivalent, which is why the extension audit is the first step of any headless project.
Is headless Magento overkill for a small store?
Sometimes, yes. If you have no development resource and your current theme serves you, a well-tuned traditional setup is a legitimate answer. Headless pays off when speed, design freedom and additional channels have a measurable revenue case — or when it arrives pre-built rather than as a bespoke project.