I've migrated over a dozen Shopify stores to headless architectures over the past three years. Some went smoothly. A few were nightmares. The difference almost always came down to planning — specifically, whether the team understood what they were actually getting into before writing the first line of code.

This guide covers everything I wish someone had told me before my first headless Shopify migration: which frontend framework to pick, how to preserve your SEO rankings, how to achieve zero downtime during the cutover, what it actually costs, and realistic timelines based on store complexity. No hand-waving. No "it depends" without explaining what it depends on.

Table of Contents

Shopify to Headless Migration: Next.js, Hydrogen & Remix Guide

Why Migrate from Shopify to Headless?

Let's get this out of the way: standard Shopify is great for most stores. If you're doing under $2M/year and your theme does what you need, you probably don't need headless. Seriously. I've talked people out of this migration more than I've talked them into it.

But there are legitimate reasons to go headless:

  • Performance ceiling: Liquid themes have a rendering bottleneck. Even with Online Store 2.0 and Dawn, you're limited by Shopify's server-side rendering pipeline. Headless stores consistently hit sub-1-second LCP scores.
  • Custom experiences: Product configurators, AR try-ons, complex filtering, personalization engines — these are painful to build in Liquid.
  • Multi-storefront: One backend powering your DTC site, wholesale portal, mobile app, and international stores.
  • Content-rich brands: If your brand relies heavily on editorial content, lookbooks, and storytelling, coupling a headless CMS with Shopify's commerce engine gives you the best of both worlds.
  • Developer experience: Your team wants to work in React/TypeScript, not Liquid. This matters more than people admit.

The performance gains are real and measurable. In 2025, Google's Core Web Vitals directly impact your search rankings. Stores I've migrated to headless typically see a 30-50% improvement in LCP and a 40-60% improvement in Total Blocking Time. That translates to measurable conversion rate improvements — Shopify's own data suggests a 1% improvement in page speed can increase conversion by up to 0.7%.

Headless Shopify Architecture Explained

When people say "headless Shopify," they mean decoupling the frontend (what customers see) from the backend (Shopify's commerce engine). You keep Shopify for products, inventory, orders, checkout, and payments. You build a custom frontend that talks to Shopify via the Storefront API.

Here's the typical architecture:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Custom Frontend│────▶│  Storefront API   │────▶│  Shopify Backend │
│  (Next.js/H2/Remix)│   │  (GraphQL)        │     │  (Products, Cart, │
│                 │     │                  │     │   Orders, etc.)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │
        ▼
┌─────────────────┐
│  Headless CMS    │
│  (Sanity, Contentful,│
│   Storyblok)     │
└─────────────────┘

Shopify Plus merchants get access to the Checkout Extensibility API, which lets you customize checkout without redirecting to Shopify's hosted checkout. For non-Plus stores, customers still get redirected to checkout.shopify.com for the actual purchase — which honestly isn't a terrible experience, but it is a UX interruption.

The Storefront API

Everything runs through Shopify's Storefront API, a GraphQL endpoint that handles:

  • Product queries and collections
  • Cart management (create, update, remove line items)
  • Customer authentication
  • Content (metafields, metaobjects)
  • Shop localization and currency

The API has rate limits — 50 cost points per second for a single app. In practice, this is rarely an issue if you're caching properly, but it can bite you during flash sales if you haven't planned for it.

# Example: Fetching a product with variants
query ProductQuery($handle: String!) {
  product(handle: $handle) {
    id
    title
    descriptionHtml
    priceRange {
      minVariantPrice {
        amount
        currencyCode
      }
    }
    variants(first: 100) {
      edges {
        node {
          id
          title
          availableForSale
          price {
            amount
          }
          selectedOptions {
            name
            value
          }
        }
      }
    }
    images(first: 10) {
      edges {
        node {
          url
          altText
          width
          height
        }
      }
    }
  }
}

Choosing Your Frontend: Next.js vs Hydrogen vs Remix

This is where most teams get stuck. Here's my honest take after building production stores with all three.

Feature Next.js 15 Hydrogen 2024.10+ Remix (Shopify)
Framework maturity Very mature, massive ecosystem Maturing, Shopify-specific Mature (merged into React Router 7)
Shopify integration Manual via Storefront API First-party, built-in hooks Good via Hydrogen UI
Hosting Vercel, Netlify, self-hosted Oxygen (Shopify) or self-hosted Anywhere, but optimized for Oxygen
Learning curve Moderate Moderate-High Moderate
Community/hiring Massive Small but growing Medium
SSR/SSG flexibility Excellent (App Router) SSR-focused (streaming) SSR-focused (loaders)
Caching control ISR, on-demand revalidation Oxygen sub-request caching Standard HTTP caching
Best for Teams with React experience, complex content needs Shopify-native teams, simple-to-medium stores Teams wanting Shopify's recommended path

Next.js: The Safe Bet

Next.js is what I recommend for most teams, especially if you're pairing Shopify with a headless CMS like Sanity or Contentful. The ecosystem is enormous, hiring is easier, and you get incredible flexibility with the App Router's server components.

The downside? You have to wire up the Shopify integration yourself. There's no official Shopify SDK for Next.js (though community packages like @shopify/hydrogen-react give you cart hooks and utilities). You'll spend more time on boilerplate.

We build a lot of headless Shopify stores with Next.js at Social Animal — it's our most requested stack for ecommerce projects.

Hydrogen: Shopify's Own Framework

Hydrogen is Shopify's official headless framework, built on top of Remix (now React Router 7). It comes with pre-built components for products, carts, and SEO — plus tight integration with Oxygen, Shopify's edge hosting platform.

The appeal is clear: less boilerplate, Shopify-optimized caching, and a deployment story that just works on Oxygen. The 2024.10 release brought significant improvements including better TypeScript support and optimistic UI updates for cart operations.

The downsides? Smaller community, fewer resources when you're stuck, and you're somewhat locked into Shopify's ecosystem. If you ever want to swap commerce backends, you're rewriting a lot more code than you would with Next.js.

Remix / React Router 7

Here's the confusing part: Remix has been merged into React Router 7. Hydrogen is built on Remix. So "Remix for Shopify" effectively means Hydrogen in most contexts.

If you want to use React Router 7 without Hydrogen's Shopify-specific abstractions, you can. You'll get the same loader/action patterns, the same streaming SSR, and full control over your Shopify integration. This makes sense if you're already a Remix team and want maximum flexibility.

My Recommendation

For content-heavy brands with complex page layouts: Next.js + headless CMS. For straightforward DTC stores that want the fastest path to production: Hydrogen on Oxygen. For teams already invested in the Remix ecosystem: React Router 7 with Hydrogen UI components.

Shopify to Headless Migration: Next.js, Hydrogen & Remix Guide - architecture

The Migration Process Step by Step

Here's the process I follow for every migration. It's boring. It works.

Phase 1: Audit and Planning (2-3 weeks)

  1. Crawl the existing site — Use Screaming Frog or Sitebulb to catalog every URL, redirect, canonical tag, and structured data block. Export this. You'll need it later.
  2. Document all integrations — Klaviyo, Yotpo reviews, loyalty programs, subscription apps (Recharge, Loop), payment gateways. Every single one.
  3. Map URL structures — Will your new URLs match the old ones? Shopify uses /products/product-handle and /collections/collection-handle. If you change these, you need redirects.
  4. Identify custom functionality — Anything beyond standard browse-and-buy. Gift cards, bundles, wholesale pricing, multi-currency, B2B.
  5. Choose your stack — Frontend framework, CMS, hosting, CDN.

Phase 2: Build the Frontend (6-12 weeks)

This is where the actual development happens. Key areas:

  • Product pages with variant selection, image galleries, reviews integration
  • Collection pages with filtering, sorting, pagination
  • Cart with real-time inventory checks and upsells
  • Search — Shopify's Predictive Search API or a third-party like Algolia
  • Customer accounts — login, order history, address management
  • CMS-driven pages — homepage, about, landing pages
  • Checkout redirect — handling the handoff to Shopify checkout
// Example: Next.js product page with ISR
import { getProduct } from '@/lib/shopify'
import { ProductDetails } from '@/components/product-details'

export async function generateStaticParams() {
  const products = await getAllProductHandles()
  return products.map((handle) => ({ handle }))
}

export default async function ProductPage({ 
  params 
}: { 
  params: { handle: string } 
}) {
  const product = await getProduct(params.handle)
  
  if (!product) notFound()

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(generateProductJsonLd(product)),
        }}
      />
      <ProductDetails product={product} />
    </>
  )
}

export const revalidate = 60 // ISR: revalidate every 60 seconds

Phase 3: Integration and QA (2-4 weeks)

Connect all third-party services. Test everything. And I mean everything:

  • Place test orders across all payment methods
  • Test discount codes, gift cards, automatic discounts
  • Verify analytics tracking (GA4, Meta Pixel, TikTok Pixel)
  • Load test the Storefront API calls under expected traffic
  • Test on actual devices, not just Chrome DevTools

Phase 4: Cutover (1-2 days)

The actual switch. More on this in the zero-downtime section below.

SEO Preservation During Migration

This is where migrations go wrong. I've seen stores lose 40% of organic traffic because someone forgot about URL redirects. Don't be that team.

URL Mapping

Create a complete URL mapping document before you write a single redirect rule. Every URL on the old site needs a destination on the new site.

OLD: /collections/summer-2024
NEW: /collections/summer-2024  ← Same? Great, no redirect needed.

OLD: /blogs/news/our-story
NEW: /journal/our-story  ← Different? 301 redirect required.

OLD: /pages/about-us
NEW: /about  ← Different? 301 redirect required.

Structured Data

Shopify themes include basic structured data. When you go headless, you're responsible for implementing it yourself. At minimum:

  • Product schema with offers, aggregateRating
  • BreadcrumbList for navigation
  • Organization for your brand
  • WebSite with SearchAction for sitelinks search
  • FAQPage where applicable

Meta Tags and Canonicals

Every page needs proper <title>, <meta description>, canonical URL, and Open Graph tags. In Next.js, use the Metadata API:

export async function generateMetadata({ params }): Promise<Metadata> {
  const product = await getProduct(params.handle)
  
  return {
    title: product.seo.title || product.title,
    description: product.seo.description || product.description,
    openGraph: {
      images: [product.featuredImage?.url],
    },
    alternates: {
      canonical: `https://yourstore.com/products/${params.handle}`,
    },
  }
}

XML Sitemap

Generate your sitemap dynamically from Shopify's data. Include products, collections, and CMS pages. Submit it to Google Search Console immediately after migration.

Pre-Migration SEO Checklist

  • Complete URL mapping document
  • 301 redirects configured and tested
  • Structured data implemented and validated
  • Meta tags pulling from Shopify SEO fields
  • XML sitemap generated dynamically
  • robots.txt configured correctly
  • Google Search Console notified of domain change (if applicable)
  • Internal links updated to new URL structure
  • Image alt texts preserved from Shopify

Zero Downtime Migration Strategy

Zero downtime isn't magic. It's DNS management and preparation.

The Blue-Green Deployment Approach

  1. Build and deploy the new site on a staging domain (e.g., new.yourstore.com)
  2. Run both sites simultaneously for at least a week, testing the new site thoroughly
  3. Configure your CDN/DNS to support instant switching (Cloudflare, Vercel, or Netlify all support this)
  4. Switch DNS to point to the new frontend — TTL should be set to 60 seconds well in advance
  5. Monitor everything: error rates, 404s, conversion rates, Core Web Vitals

The Proxy Approach (Even Safer)

For stores doing over $1M/month, I prefer a proxy-based migration:

  1. Put a reverse proxy (Cloudflare Workers, Vercel Edge Middleware) in front of both the old and new sites
  2. Route traffic page by page — start with a low-risk page like /about
  3. Gradually move pages to the new frontend over 2-4 weeks
  4. Monitor each page's performance before moving the next batch
  5. Product and collection pages go last (highest revenue risk)

This approach adds complexity but lets you catch issues before they affect your entire store.

// Vercel Edge Middleware example for gradual migration
import { NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
  
  // Pages already migrated to new frontend
  const migratedPaths = ['/about', '/contact', '/journal']
  
  if (migratedPaths.some(path => pathname.startsWith(path))) {
    return NextResponse.next() // Serve from new frontend
  }
  
  // Everything else proxies to old Shopify store
  return NextResponse.rewrite(
    new URL(pathname, 'https://old-store.myshopify.com')
  )
}

Pricing and Timeline Breakdown

Let's talk real numbers. These are based on projects I've seen in 2025, ranging from simple DTC stores to complex multi-market operations.

Store Complexity Timeline Agency Cost Freelancer Cost
Simple (< 50 products, basic pages, standard checkout) 8-12 weeks $40,000 - $75,000 $20,000 - $40,000
Medium (50-500 products, CMS, subscriptions, multi-currency) 12-20 weeks $75,000 - $150,000 $40,000 - $80,000
Complex (500+ products, B2B+DTC, custom checkout, multiple integrations) 20-32 weeks $150,000 - $300,000+ $80,000 - $150,000

Ongoing Costs

Don't forget the recurring expenses:

  • Shopify Plus: $2,300/month (required for checkout extensibility, recommended for headless)
  • Hosting: $20-500/month (Vercel Pro is $20/user, Oxygen is included with Shopify)
  • Headless CMS: $0-500/month (Sanity, Contentful, Storyblok all have free tiers)
  • Search: $0-500/month if using Algolia or similar
  • Maintenance: Budget 10-15% of initial build cost annually

For teams exploring what a headless Shopify migration would cost for their specific situation, we break down our pricing approach here. We're also happy to scope things out over a quick call.

Common Migration Pitfalls

1. Underestimating the Cart

The cart seems simple until you factor in: discount codes, automatic discounts, gift cards, line item properties, cart notes, estimated shipping, tax calculations, and cart-level metafields. Budget twice the time you think you need for cart functionality.

2. Forgetting About Apps

That Shopify app ecosystem you rely on? Most apps inject JavaScript into your Liquid theme. Going headless means you need API-based alternatives or custom implementations for reviews, wishlists, loyalty programs, and more.

3. Checkout Customization

Without Shopify Plus ($2,300/month), you can't customize the checkout experience. Customers will be redirected to Shopify's hosted checkout, which creates a visual disconnect. Plus merchants can use Checkout Extensibility, but it's still more limited than a fully custom checkout.

4. Not Performance Testing Early

The Storefront API adds latency. If you're making 8 API calls to render a product page, you'll feel it. Cache aggressively, use GraphQL fragments to minimize over-fetching, and implement streaming SSR where possible.

5. Ignoring the Content Team

Your marketing team managed content in Shopify's admin. Now they need a headless CMS. Budget time for training and building a content editing experience that's actually pleasant to use. This is where headless CMS development expertise really matters.

When Headless Isn't the Right Move

I'll be straight with you: headless Shopify isn't for everyone. Don't migrate if:

  • Your store does under $1M/year and you don't have complex customization needs
  • You don't have budget for ongoing development and maintenance
  • Your team doesn't have React developers (or budget to hire/contract them)
  • You're happy with your current theme's performance and features
  • You're primarily looking for a "cool tech" story rather than solving real business problems

Shopify's Online Store 2.0 with a well-optimized theme can score 90+ on Lighthouse. Sometimes the right answer is to optimize what you have rather than rebuild from scratch.

If you're on the fence, consider starting with a hybrid approach: keep your Shopify theme but build specific high-impact pages (like your homepage or landing pages) as headless. You can use Shopify's Storefront API alongside your existing theme. This lets you prove value before committing to a full migration.

FAQ

How long does it take to migrate from Shopify to headless?

For a typical medium-complexity store, expect 12-20 weeks from kickoff to launch. Simple stores with fewer products and basic functionality can ship in 8-12 weeks. Complex multi-market stores with custom checkout and extensive integrations often take 20-32 weeks. The audit and planning phase alone should be 2-3 weeks — don't skip it.

Will I lose my SEO rankings when migrating to headless Shopify?

Not if you do it right. The keys are: maintain the same URL structure (or set up proper 301 redirects), implement structured data on every page type, preserve meta tags and canonical URLs, and submit an updated sitemap to Google Search Console immediately after launch. I typically see a 1-2 week fluctuation in rankings post-migration, followed by improvement once Google recognizes the better Core Web Vitals scores.

Do I need Shopify Plus for headless?

Technically, no. The Storefront API is available on all Shopify plans. However, Shopify Plus gives you Checkout Extensibility (customize the checkout experience), higher API rate limits, and access to Oxygen hosting. For serious headless projects, Plus at $2,300/month is almost always worth it.

What's the difference between Hydrogen and using Next.js with Shopify?

Hydrogen is Shopify's official headless framework built on Remix/React Router 7. It includes Shopify-specific components, hooks, and utilities out of the box, plus optimized deployment on Oxygen. Next.js requires you to build the Shopify integration yourself but gives you a larger ecosystem, more hosting options, and better support for complex content architectures. Most agencies, including ours, have strong opinions here based on the specific project requirements.

Can I migrate to headless Shopify with zero downtime?

Yes, using either a blue-green deployment (DNS switch) or a gradual proxy-based migration. The blue-green approach switches all traffic at once via DNS, while the proxy approach migrates pages incrementally over weeks. Both work. The proxy approach is safer for high-revenue stores but adds complexity.

How much does a headless Shopify migration cost?

Agency costs typically range from $40,000 for a simple store to $300,000+ for complex multi-market operations. Freelancer rates are roughly 50-60% of agency costs but may come with less project management structure and fewer specialists. Ongoing costs include Shopify Plus ($2,300/month), hosting ($20-500/month), CMS ($0-500/month), and maintenance (10-15% of build cost annually).

Should I use Astro instead of Next.js or Hydrogen for headless Shopify?

Astro is a great choice for content-heavy sites with islands of interactivity, and we've built several Astro-powered storefronts. It works well for catalog-style stores where most pages are static and you only need React (or Svelte, Vue) for interactive components like the cart. However, for stores with heavy client-side interactivity — real-time inventory, complex filtering, instant search — Next.js or Hydrogen's full React runtime is usually a better fit.

What happens to my Shopify apps after migrating to headless?

Most Shopify apps that inject frontend code (popups, widgets, review displays) won't work out of the box. You'll need to either use the app's API directly, find a headless-compatible alternative, or build custom implementations. Apps that only operate on the backend (inventory management, shipping, ERP integrations) typically continue working without changes. Always audit your app stack during the planning phase.