Magento 2 to Headless: A Senior Developer’s Migration Guide

The Storefront That's Holding You Back

You have a mature Magento 2 store. Products, inventory, promotions, checkout — it all works. But your PageSpeed score is in the 30s on mobile, your marketing team can't ship a landing page without a developer, and your developers can't ship anything without touching a PHP template system that nobody wants to learn.

The backend isn't the problem. The frontend is — and you can decouple them. Headless Commerce means keeping Magento as the source of truth for products and orders, while rebuilding the storefront in Next.js with full control over performance, design, and deployment.

Architectural Advantages

Decoupling the frontend provides three critical benefits:

1. Performance: Next.js allows for Static Site Generation (SSG) and Incremental Static Regeneration (ISR), resulting in sub-second page loads that are nearly impossible in a standard Magento theme.
2. Developer Experience: Senior Developers can leverage modern tools like TypeScript, Tailwind CSS, and Framer Motion without being constrained by Magento's complex XML layout system.
3. Omnichannel Ready: A headless backend can serve products to your web store, mobile apps, and even smart displays through a single GraphQL API.

Fetching Products via GraphQL

Magento 2's GraphQL API is the bridge between backend and frontend. A product listing page in Next.js fetches directly from it:

// lib/magento.ts
const PRODUCT_QUERY = `
  query GetProducts($search: String!) {
    products(search: $search, pageSize: 12) {
      items {
        id
        name
        sku
        price_range {
          minimum_price {
            regular_price { value currency }
          }
        }
        thumbnail { url label }
      }
    }
  }
`

export async function getProducts(search: string) {
  const res = await fetch(process.env.MAGENTO_GRAPHQL_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: PRODUCT_QUERY, variables: { search } }),
    next: { revalidate: 60 }, // ISR — revalidate every 60 seconds
  })
  const { data } = await res.json()
  return data.products.items
}

With Next.js ISR (revalidate: 60), product pages are statically generated and refreshed in the background — sub-second loads without sacrificing live inventory data.

Key Migration Challenges

• Cart & Session State: Cart data lives in Magento's session. You'll need the GraphQL cart mutations and a client-side store (Zustand works well) to keep them in sync.
• Checkout Decision: Keep the Magento checkout behind a redirect, or rebuild it in React. The redirect approach is lower risk for the initial migration.
• SEO Continuity: Map every Magento URL to its Next.js equivalent before go-live and set up 301 redirects. One missed product URL can cost you hard-won search rankings.

Conclusion

The migration doesn't have to be all-or-nothing. A common approach is to build the Next.js storefront in parallel, starting with the product listing and detail pages, then cut over by routing traffic via a CDN rewrite rule. The Magento backend keeps running — you're just replacing the layer your customers actually see. Once the new frontend is stable, checkout and account pages follow.

Start with a single product category page. It's enough to validate the GraphQL integration, the ISR caching, and the deployment pipeline before committing to the full migration.

Sources & References

• Adobe Commerce (Magento) Documentation
• Next.js Commerce Documentation
• GraphQL & Magento 2: Developer Guide
• commercetools: Headless Commerce Platform