What headless means for a Magento shop
A classic Magento installation couples the front-end directly to the backend. Luma or Hyva renders server-side HTML through Magento's PHP layer, including all business logic. Every page visit triggers Magento's full request lifecycle: PHP bootstrap, layout rendering, block rendering, template rendering.
In a headless architecture you split that coupling apart. Magento runs as an API-first backend. It manages:
- ▸Product catalogue: attributes, categories, configurable and grouped products
- ▸Order management: checkout flow, order status, returns
- ▸Inventory management: MSI sources, salable qty per warehouse
- ▸Customer accounts: order history, addresses, wishlist
- ▸Promotions and price rules: catalogue and cart rules
- ▸Payment integrations: Mollie, Stripe and others via Magento payment providers
The Next.js frontend fetches data via the Magento GraphQL API and renders the storefront as static or server-rendered React pages. Visitors never see Magento's PHP layer. They see HTML generated in milliseconds via Next.js Server Components or edge rendering.
When headless makes sense for your Magento shop
Headless is not a default choice. It adds complexity to the architecture, and that complexity must deliver something. The following situations justify that investment:
- ▸LCP ceiling on the classic storefront: Luma shops regularly hit 8 to 14 seconds PSI lab LCP on mobile. Hyva brings that to 3 to 5 seconds. Next.js on Magento GraphQL reaches 0.6 to 1.2 seconds in CrUX for product pages with proper image prioritisation.
- ▸Multi-channel without Adobe Commerce licence: you want to serve the same catalogue through a webshop, a mobile app and a B2B portal. With Magento as an API backend you have one data layer for all channels, without a Commerce licence.
- ▸Team with React expertise: your frontend developers work in React daily. They are more productive in Next.js than in Magento's template system, LESS and RequireJS.
- ▸Design freedom beyond Hyva: Hyva is fast, but it remains a Magento theme. If the design substantially differs from what a theme can handle, headless is the shorter path.
- ▸PWA Studio considered too complex: Magento's own PWA Studio has a steep learning curve and limited community support. Next.js is more familiar for most React developers.
It is not about following trends. It is about whether the complexity of a headless architecture delivers something concrete for your specific situation.
When headless is not the right choice
I do not advise headless to everyone. There are situations where it costs more than it delivers:
- ✕Small catalogue with fewer than 500 products: Hyva Themes already achieves excellent performance here. The extra architecture layer adds no visible value for the visitor.
- ✕No frontend development capacity: a headless storefront requires ongoing frontend maintenance by developers who know React and Next.js. Without that team, maintenance becomes a bottleneck.
- ✕Payment providers that couple tightly to the Magento storefront: some payment providers integrate via Magento modules that require direct access to the PHP frontend. That can be worked around, but requires extra work per provider.
- ✕Small budgets without a growth path: headless migrations are substantial. If the business case is not clear, a Hyva migration is often the better first step.
- ✕Magento functionality that relies heavily on third-party modules with their own frontend: extensions like Amasty Page Builder or custom checkout modules are built for the Magento storefront. They do not automatically integrate into a headless frontend.
If I doubt whether headless is the right choice for your situation, I say so. An architecture audit costs less than a migration that gets stuck halfway.
The architecture I build
For headless Magento I use a fixed set of choices, based on what works in production:
- ▸Next.js App Router: Server Components for static and server-rendered pages, Client Components only where interaction is needed. No unnecessary JavaScript sent to the browser.
- ▸Magento GraphQL API: product catalogue, category navigation, cart operations, checkout, customer account and order history via the Magento GraphQL layer. REST only where GraphQL falls short.
- ▸Algolia for search (optional): Magento's built-in catalogue search does not scale well with large catalogues. Algolia synchronises the catalogue and delivers instant search with faceted filtering.
- ▸Mollie or Stripe via Magento order API: payment goes through the Magento backend. Next.js sends the order to Magento, Magento processes the payment provider. The visitor sees a React checkout form, payment is handled via the existing Magento payment provider.
- ▸ISR for product pages: Incremental Static Regeneration for product pages ensures static HTML is available at the edge, without every visitor triggering a GraphQL call.
- ▸Cloudflare Workers for traffic splitting during migration: headless and classic run in parallel, Cloudflare routes a configurable percentage of traffic to the new frontend.
Each of these choices is open for discussion. If your team prefers Elasticsearch over Algolia, or if your payment provider requires a different integration, I adapt the architecture.
How the migration unfolds
Headless migrations are risky when they go live all at once. I use a parallel deploy strategy that minimises downtime and risk.
The new Next.js frontend is built alongside the existing Magento storefront. Both run on the same Magento 2 backend. Via a Cloudflare Worker I arrange traffic splitting: first 5 percent of traffic to the new frontend, then 20 percent, then 50 percent. Each step is monitored on conversion, error rates and Core Web Vitals. If a step shows problems, traffic immediately reverts to the classic storefront without visitors noticing.
After the hard cutover the classic Magento storefront stays on as a fallback. Only after a stable period, once all edge cases are resolved, is the classic storefront switched off. The Magento Admin panel, extensions and order management remain untouched throughout the migration.
-- Anonymous client case
8,000 products, LCP ceiling on classic storefront, headless migration
A Magento 2 shop in the B2C market, 8,000 products, Hyva theme, hosted on Hypernode. The mobile LCP stood at 7 to 9 seconds in PSI lab for category pages due to heavy filter JavaScript and an LCP image that only loaded after the filter component had initialised.
After the headless migration to Next.js App Router with Magento GraphQL and Algolia for filtering: category pages are statically generated via ISR with hourly revalidation. The filter component is a Client Component, but loads after the LCP image. The LCP image gets fetchpriority=high and loads server-side as a priority.
Magento Admin remained intact. All existing orders, customer accounts and product data stayed in Magento. The frontend team no longer has to work with Magento's template system; they work in Next.js and TypeScript. The Algolia integration fully replaced the slow Magento layered navigation.
What I do not do
Headless migrations are sometimes sold as a solution without the problem diagnosis being correct. I do not do the following:
- ✕Magento PWA Studio implementations without good reason: PWA Studio is Magento's own headless framework, but it has a smaller developer community compared to Next.js. I use it only if the team is already working with it.
- ✕Headless without a broader architecture audit: a headless frontend on a poorly configured Magento backend does not solve the backend problems. TTFB of 2 seconds on GraphQL calls undermines any frontend gain.
- ✕Deciding the framework choice for the client team: if your team works with Nuxt, Remix or another React framework, I will not claim Next.js is the only correct choice. I will make the trade-offs clear.
- ✕Migrations without a fallback strategy: a headless migration without parallel deploy is an unnecessary risk. I always build a return path.
If an architecture choice does not fit your situation, I say so directly. A migration that gets stuck halfway costs more than the migration itself.
Scope and pricing
The investment for a headless Magento migration depends on the size of the catalogue, the number of integrations, the complexity of the checkout and the availability of the client team for collaboration. There is no standard package.
I work on an hourly basis or based on a fixed scope after an architecture session. Get in touch to discuss the situation.